From 3f6168352cbe03984b978b2dd744a7ae809f7036 Mon Sep 17 00:00:00 2001 From: John Jawed Date: Wed, 31 Dec 2008 00:38:41 +0000 Subject: [PATCH] PECL OAuth documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@272335 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/oauth/book.xml | 47 +++++++ reference/oauth/configure.xml | 32 +++++ reference/oauth/constants.xml | 80 +++++++++++ reference/oauth/oauth.xml | 68 ++++++++++ reference/oauth/oauth/construct.xml | 88 ++++++++++++ reference/oauth/oauth/fetch.xml | 113 ++++++++++++++++ reference/oauth/oauth/getaccesstoken.xml | 126 ++++++++++++++++++ reference/oauth/oauth/getlastresponse.xml | 64 +++++++++ reference/oauth/oauth/getlastresponseinfo.xml | 66 +++++++++ reference/oauth/oauth/getrequesttoken.xml | 111 +++++++++++++++ reference/oauth/oauth/setauthtype.xml | 91 +++++++++++++ reference/oauth/oauth/setnonce.xml | 76 +++++++++++ reference/oauth/oauth/settoken.xml | 91 +++++++++++++ reference/oauth/oauth/setversion.xml | 65 +++++++++ reference/oauth/oauthexception.xml | 116 ++++++++++++++++ reference/oauth/reference.xml | 31 +++++ reference/oauth/setup.xml | 52 ++++++++ reference/oauth/versions.xml | 51 +++++++ 18 files changed, 1368 insertions(+) create mode 100644 reference/oauth/book.xml create mode 100644 reference/oauth/configure.xml create mode 100644 reference/oauth/constants.xml create mode 100644 reference/oauth/oauth.xml create mode 100644 reference/oauth/oauth/construct.xml create mode 100644 reference/oauth/oauth/fetch.xml create mode 100644 reference/oauth/oauth/getaccesstoken.xml create mode 100644 reference/oauth/oauth/getlastresponse.xml create mode 100644 reference/oauth/oauth/getlastresponseinfo.xml create mode 100644 reference/oauth/oauth/getrequesttoken.xml create mode 100644 reference/oauth/oauth/setauthtype.xml create mode 100644 reference/oauth/oauth/setnonce.xml create mode 100644 reference/oauth/oauth/settoken.xml create mode 100644 reference/oauth/oauth/setversion.xml create mode 100644 reference/oauth/oauthexception.xml create mode 100644 reference/oauth/reference.xml create mode 100644 reference/oauth/setup.xml create mode 100644 reference/oauth/versions.xml diff --git a/reference/oauth/book.xml b/reference/oauth/book.xml new file mode 100644 index 0000000000..d53a3e4d40 --- /dev/null +++ b/reference/oauth/book.xml @@ -0,0 +1,47 @@ + + + + + + + OAuth + + + &reftitle.intro; + + This extension provides OAuth consumer bindings. OAuth is an + authorization protocol built on top of HTTP which allows applications + to securely access data without having to store usernames and + passwords. + + + + &reference.oauth.setup; + &reference.oauth.constants; + &reference.oauth.reference; + &reference.oauth.oauth; + &reference.oauth.oauthexception; + + + + + diff --git a/reference/oauth/configure.xml b/reference/oauth/configure.xml new file mode 100644 index 0000000000..fcf611f5ba --- /dev/null +++ b/reference/oauth/configure.xml @@ -0,0 +1,32 @@ + + + +
+ &reftitle.install; + + &pecl.info; + &url.pear.package;oauth + +
+ + + diff --git a/reference/oauth/constants.xml b/reference/oauth/constants.xml new file mode 100644 index 0000000000..588fed2410 --- /dev/null +++ b/reference/oauth/constants.xml @@ -0,0 +1,80 @@ + + + + + &reftitle.constants; + &extension.constants; + + + + + OAUTH_SIG_METHOD_HMACSHA1 + (string) + + + + OAuth HMAC-SHA1 signature method + + + + + + OAUTH_AUTH_TYPE_AUTHORIZATION + (string) + + + + This constant represents putting OAuth parameters in the + Authorization header. + + + + + + OAUTH_AUTH_TYPE_URI + (string) + + + + This constant represents putting OAuth parameters in the request + URI. + + + + + + OAUTH_AUTH_TYPE_FORM + (string) + + + + This constant represents putting OAuth parameters as part of the + HTTP POST body. + + + + + + + + + diff --git a/reference/oauth/oauth.xml b/reference/oauth/oauth.xml new file mode 100644 index 0000000000..12c56f5229 --- /dev/null +++ b/reference/oauth/oauth.xml @@ -0,0 +1,68 @@ + + + + + The OAuth class + OAuth + + + + +
+ &reftitle.intro; + + The OAuth extension provides a simple interface to interact with + data providers using the OAuth HTTP specification to protect + private resources. + +
+ + +
+ &reftitle.classsynopsis; + + + + OAuth + + + + + OAuth + + + + + Methods + + + + +
+ + + + &reference.oauth.entities.oauth; + + + + diff --git a/reference/oauth/oauth/construct.xml b/reference/oauth/oauth/construct.xml new file mode 100644 index 0000000000..74aa1809b2 --- /dev/null +++ b/reference/oauth/oauth/construct.xml @@ -0,0 +1,88 @@ + + + + + + OAuth::__construct + Create a new OAuth object + + + + &reftitle.description; + + OAuth::__construct + stringconsumer_key + stringconsumer_secret + stringsignature_method + stringauth_type + + + Creates a new OAuth object + + + + + &reftitle.parameters; + + + + consumer_key + + + The consumer key provided by the service provider. + + + + + consumer_secret + + + The consumer secret provided by the service provider. + + + + + signature_method + + + This optional parameter defines which signature method to use, by default it is OAUTH_SIG_METHOD_HMACSHA1 (HMAC-SHA1). + + + + + auth_type + + + This optional parameter defines how to pass the OAuth parameters + to a consumer, by default it is + OAUTH_AUTH_TYPE_AUTHORIZATION (in the + Authorization header). + + + + + + + + + + diff --git a/reference/oauth/oauth/fetch.xml b/reference/oauth/oauth/fetch.xml new file mode 100644 index 0000000000..b73fbb7940 --- /dev/null +++ b/reference/oauth/oauth/fetch.xml @@ -0,0 +1,113 @@ + + + + + + OAuth::fetch + Fetch an OAuth protected resource. + + + + &reftitle.description; + + public voidOAuth::fetch + stringprotected_resource_url + arrayextra_parameters + + + Fetch a resource protected by OAuth. + + + + + &reftitle.parameters; + + + + protected_resource_url + + + URL to the OAuth protected resource. + + + + + extra_parameters + + + Extra parameters to send with the request for the resource. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + <function>OAuth::fetch</function> example + +setToken("access_token","access_token_secret"); + + $oauth->fetch("http://photos.example.net/photo?file=vacation.jpg"); + + $response_info = $oauth->getLastResponseInfo(); + header("Content-Type: {$response_info["content_type"]}"); + echo $oauth->getLastResponse(); +} catch(OAuthException $E) { + echo "Exception caught!\n"; + echo "Response: ". $E->lastResponse . "\n"; +} +?> +]]> + + + + + + + &reftitle.seealso; + + + OAuth::getLastResponse + OAuth::getLastResponseInfo + OAuth::setToken + + + + + + + diff --git a/reference/oauth/oauth/getaccesstoken.xml b/reference/oauth/oauth/getaccesstoken.xml new file mode 100644 index 0000000000..339c31f623 --- /dev/null +++ b/reference/oauth/oauth/getaccesstoken.xml @@ -0,0 +1,126 @@ + + + + + + OAuth::getAccessToken + The getAccessToken purpose + + + + &reftitle.description; + + public arrayOAuth::getAccessToken + stringaccess_token_url + stringauth_session_handle + + + Fetch an access token, secret and any additional response parameters from the service provider. + + + + + &reftitle.parameters; + + + + access_token_url + + + URL to the access token API. + + + + + auth_session_handle + + + Authorization session handle, this parameter does not have any + citation in the core OAuth 1.0 specification but may be + implemented by large providers. + See ScalableOAuth + for more information. + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing the parsed OAuth response on success or NULL on failure. + + + + + &reftitle.examples; + + + <function>OAuth::getAccessToken</function> example + +setToken($request_token,$request_token_secret); + $access_token_info = $oauth->getRequestToken("https://example.com/oauth/access_token"); + if(!empty($access_token_info)) { + print_r($access_token_info); + } else { + print "Failed fetching access token, response was: " . $oauth->getLastResponse(); + } +} catch(OAuthException $E) { + echo "Response: ". $E->lastResponse . "\n"; +} +?> +]]> + + &example.outputs.similar; + + some_token + [oauth_token_secret] => some_token_secret +) +]]> + + + + + + + &reftitle.seealso; + + + OAuth::getLastResponse + OAuth::getLastResponseInfo + OAuth::setToken + + + + + + + diff --git a/reference/oauth/oauth/getlastresponse.xml b/reference/oauth/oauth/getlastresponse.xml new file mode 100644 index 0000000000..12d245c560 --- /dev/null +++ b/reference/oauth/oauth/getlastresponse.xml @@ -0,0 +1,64 @@ + + + + + + OAuth::getLastResponse + Get the last response + + + + &reftitle.description; + + public stringOAuth::getLastResponse + + + + Get the raw response of the most recent request. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a string containing the last response. + + + + + &reftitle.seealso; + + + OAuth::getLastResponseInfo + OAuth::fetch + + + + + + + diff --git a/reference/oauth/oauth/getlastresponseinfo.xml b/reference/oauth/oauth/getlastresponseinfo.xml new file mode 100644 index 0000000000..2bb325a0cd --- /dev/null +++ b/reference/oauth/oauth/getlastresponseinfo.xml @@ -0,0 +1,66 @@ + + + + + + OAuth::getLastResponseInfo + Get HTTP information about the last response + + + + &reftitle.description; + + public arrayOAuth::getLastResponseInfo + + + + Get HTTP information about the last response. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns an array containing the response information for the last + request. Constants from curl_getinfo may be + used. + + + + + &reftitle.seealso; + + + OAuth::fetch + OAuth::getLastResponse + + + + + + + diff --git a/reference/oauth/oauth/getrequesttoken.xml b/reference/oauth/oauth/getrequesttoken.xml new file mode 100644 index 0000000000..14545d7263 --- /dev/null +++ b/reference/oauth/oauth/getrequesttoken.xml @@ -0,0 +1,111 @@ + + + + + + OAuth::getRequestToken + Fetch a request token + + + + &reftitle.description; + + public arrayOAuth::getRequestToken + stringrequest_token_url + + + Fetch a request token, secret and any additional response parameters from the service provider. + + + + + &reftitle.parameters; + + + + request_token_url + + + URL to the request token API. + + + + + + + + + &reftitle.returnvalues; + + Returns an array containing the parsed OAuth response on success or NULL on failure. + + + + + &reftitle.examples; + + + <function>OAuth::getRequestToken</function> example + +getRequestToken("https://example.com/oauth/request_token"); + if(!empty($request_token_info)) { + print_r($request_token_info); + } else { + print "Failed fetching request token, response was: " . $oauth->getLastResponse(); + } +} catch(OAuthException $E) { + echo "Response: ". $E->lastResponse . "\n"; +} +?> +]]> + + &example.outputs.similar; + + some_token + [oauth_token_secret] => some_token_secret +) +]]> + + + + + + + &reftitle.seealso; + + + OAuth::getLastResponse + OAuth::getLastResponseInfo + + + + + + + diff --git a/reference/oauth/oauth/setauthtype.xml b/reference/oauth/oauth/setauthtype.xml new file mode 100644 index 0000000000..6fe90fc210 --- /dev/null +++ b/reference/oauth/oauth/setauthtype.xml @@ -0,0 +1,91 @@ + + + + + + OAuth::setAuthType + The setAuthType purpose + + + + &reftitle.description; + + public boolOAuth::setAuthType + stringauth_type + + + Set where the OAuth parameters should be passed. + + + + + &reftitle.parameters; + + + + auth_type + + + auth_type can be one of the following flags (in order of decreasing preference as per OAuth 1.0 section 5.2): + + + OAUTH_AUTH_TYPE_AUTHORIZATION + + + Pass the OAuth parameters in the HTTP Authorization header. + + + + + OAUTH_AUTH_TYPE_FORM + + + Append the OAuth parameters to the HTTP POST request body. + + + + + OAUTH_AUTH_TYPE_URI + + + Append the OAuth parameters to the request URI. + + + + + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + + diff --git a/reference/oauth/oauth/setnonce.xml b/reference/oauth/oauth/setnonce.xml new file mode 100644 index 0000000000..013a9a25f4 --- /dev/null +++ b/reference/oauth/oauth/setnonce.xml @@ -0,0 +1,76 @@ + + + + + + OAuth::setNonce + Set the nonce for subsequent requests + + + + &reftitle.description; + + public boolOAuth::setNonce + stringnonce + + + Sets the nonce for all subsequent requests. + + + + + &reftitle.parameters; + + + + nonce + + + The value for oauth_nonce. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + OAuth::setToken + OAuth::setAuthType + OAuth::setVersion + + + + + + + diff --git a/reference/oauth/oauth/settoken.xml b/reference/oauth/oauth/settoken.xml new file mode 100644 index 0000000000..d0579a92c9 --- /dev/null +++ b/reference/oauth/oauth/settoken.xml @@ -0,0 +1,91 @@ + + + + + + OAuth::setToken + Sets the token and secret + + + + &reftitle.description; + + public boolOAuth::setToken + stringtoken + stringtoken_secret + + + Set the token and secret for subsequent requests. + + + + + &reftitle.parameters; + + + + token + + + The OAuth token. + + + + + token_secret + + + The OAuth token secret. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; + + + <function>OAuth::setToken</function> example + +setToken("token","token-secret"); +?> +]]> + + + + + + + + diff --git a/reference/oauth/oauth/setversion.xml b/reference/oauth/oauth/setversion.xml new file mode 100644 index 0000000000..6ee4bf0a3c --- /dev/null +++ b/reference/oauth/oauth/setversion.xml @@ -0,0 +1,65 @@ + + + + + + OAuth::setVersion + Set the OAuth version + + + + &reftitle.description; + + public boolOAuth::setVersion + stringversion + + + Sets the OAuth version for subsequent requests + + + + + &reftitle.parameters; + + + + version + + + OAuth version, default value is always "1.0" + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + + diff --git a/reference/oauth/oauthexception.xml b/reference/oauth/oauthexception.xml new file mode 100644 index 0000000000..b0a601a9f6 --- /dev/null +++ b/reference/oauth/oauthexception.xml @@ -0,0 +1,116 @@ + + + + + + OAuthException class + OAuthException + + + + +
+ &reftitle.intro; + + This exception is thrown when exceptional errors when using the OAuth extension and contains useful debugging information. + +
+ + +
+ &reftitle.classsynopsis; + + + + OAuthException + + + + + OAuthException + + + + extends + Exception + + + + Properties + + public + lastResponse + + + Inherited methods + + + + + +
+ + + +
+ &reftitle.properties; + + + message + + A human readable message about what went wrong + + + + code + + Exception code + + + + file + + File where exception was thrown + + + + line + + File where exception was thrown + + + + lastResponse + + The response of the exception which occured, if any + + + +
+ + + + + + + + diff --git a/reference/oauth/reference.xml b/reference/oauth/reference.xml new file mode 100644 index 0000000000..81355aceeb --- /dev/null +++ b/reference/oauth/reference.xml @@ -0,0 +1,31 @@ + + + + + OAuth &Functions; + + &reference.oauth.entities.functions; + + + + + diff --git a/reference/oauth/setup.xml b/reference/oauth/setup.xml new file mode 100644 index 0000000000..9dc59300cf --- /dev/null +++ b/reference/oauth/setup.xml @@ -0,0 +1,52 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + + PECL/oauth requires PHP 5.1 or newer, ext/hash and libcurl with HTTPS support. + +
+ + + &reference.oauth.configure; + + + +
+ &reftitle.runtime; + &no.config; +
+ + +
+ &reftitle.resources; + &no.resource; +
+ + + + + diff --git a/reference/oauth/versions.xml b/reference/oauth/versions.xml new file mode 100644 index 0000000000..1cdcbab868 --- /dev/null +++ b/reference/oauth/versions.xml @@ -0,0 +1,51 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +