5 * @(#) $Id: oauth_client.php,v 1.58 2013/04/11 09:33:16 mlemos Exp $
10 {metadocument}<?xml version="1.0" encoding="ISO-8859-1" ?>
13 <package>net.manuellemos.oauth</package>
15 <version>@(#) $Id: oauth_client.php,v 1.58 2013/04/11 09:33:16 mlemos Exp $</version>
16 <copyright>Copyright © (C) Manuel Lemos 2012</copyright>
17 <title>OAuth client</title>
18 <author>Manuel Lemos</author>
19 <authoraddress>mlemos-at-acm.org</authoraddress>
23 <purpose>This class serves two main purposes:<paragraphbreak />
24 1) Implement the OAuth protocol to retrieve a token from a server to
25 authorize the access to an API on behalf of the current
26 user.<paragraphbreak />
27 2) Perform calls to a Web services API using a token previously
28 obtained using this class or a token provided some other way by the
29 Web services provider.</purpose>
30 <usage>Regardless of your purposes, you always need to start calling
31 the class <functionlink>Initialize</functionlink> function after
32 initializing setup variables. After you are done with the class,
33 always call the <functionlink>Finalize</functionlink> function at
34 the end.<paragraphbreak />
35 This class supports either OAuth protocol versions 1.0, 1.0a and
36 2.0. It abstracts the differences between these protocol versions,
37 so the class usage is the same independently of the OAuth
38 version of the server.<paragraphbreak />
39 The class also provides built-in support to several popular OAuth
40 servers, so you do not have to manually configure all the details to
41 access those servers. Just set the
42 <variablelink>server</variablelink> variable to configure the class
43 to access one of the built-in supported servers.<paragraphbreak />
44 If you need to access one type of server that is not yet directly
45 supported by the class, you need to configure it explicitly setting
46 the variables: <variablelink>oauth_version</variablelink>,
47 <variablelink>url_parameters</variablelink>,
48 <variablelink>authorization_header</variablelink>,
49 <variablelink>request_token_url</variablelink>,
50 <variablelink>dialog_url</variablelink>,
51 <variablelink>offline_dialog_url</variablelink>,
52 <variablelink>append_state_to_redirect_uri</variablelink> and
53 <variablelink>access_token_url</variablelink>.<paragraphbreak />
54 Before proceeding to the actual OAuth authorization process, you
55 need to have registered your application with the OAuth server. The
56 registration provides you values to set the variables
57 <variablelink>client_id</variablelink> and
58 <variablelink>client_secret</variablelink>.<paragraphbreak />
59 You also need to set the variables
60 <variablelink>redirect_uri</variablelink> and
61 <variablelink>scope</variablelink> before calling the
62 <functionlink>Process</functionlink> function to make the class
63 perform the necessary interactions with the OAuth
64 server.<paragraphbreak />
65 The OAuth protocol involves multiple steps that include redirection
66 to the OAuth server. There it asks permission to the current user to
67 grant your application access to APIs on his/her behalf. When there
68 is a redirection, the class will set the
69 <variablelink>exit</variablelink> variable to
70 <booleanvalue>1</booleanvalue>. Then your script should exit
71 immediately without outputting anything.<paragraphbreak />
72 When the OAuth access token is successfully obtained, the following
73 variables are set by the class with the obtained values:
74 <variablelink>access_token</variablelink>,
75 <variablelink>access_token_secret</variablelink>,
76 <variablelink>access_token_expiry</variablelink>,
77 <variablelink>access_token_type</variablelink>. You may want to
78 store these values to use them later when calling the server
79 APIs.<paragraphbreak />
80 If there was a problem during OAuth authorization process, check the
81 variable <variablelink>authorization_error</variablelink> to
82 determine the reason.<paragraphbreak />
83 Once you get the access token, you can call the server APIs using
84 the <functionlink>CallAPI</functionlink> function. Check the
85 <variablelink>access_token_error</variablelink> variable to
86 determine if there was an error when trying to to call the
87 API.<paragraphbreak />
88 If for some reason the user has revoked the access to your
89 application, you need to ask the user to authorize your application
90 again. First you may need to call the function
91 <functionlink>ResetAccessToken</functionlink> to reset the value of
92 the access token that may be cached in session variables.</usage>
98 class oauth_client_class
107 <purpose>Store the message that is returned when an error
109 <usage>Check this variable to understand what happened when a call to
110 any of the class functions has failed.<paragraphbreak />
111 This class uses cumulative error handling. This means that if one
112 class functions that may fail is called and this variable was
113 already set to an error message due to a failure in a previous call
114 to the same or other function, the function will also fail and does
115 not do anything.<paragraphbreak />
116 This allows programs using this class to safely call several
117 functions that may fail and only check the failure condition after
118 the last function call.<paragraphbreak />
119 Just set this variable to an empty string to clear the error
134 <purpose>Control whether debug output is enabled</purpose>
135 <usage>Set this variable to <booleanvalue>1</booleanvalue> if you
136 need to check what is going on during calls to the class. When
137 enabled, the debug output goes either to the variable
138 <variablelink>debug_output</variablelink> and the PHP error log.</usage>
148 <name>debug_http</name>
152 <purpose>Control whether the dialog with the remote Web server
153 should also be logged.</purpose>
154 <usage>Set this variable to <booleanvalue>1</booleanvalue> if you
155 want to inspect the data exchange with the OAuth server.</usage>
160 var $debug_http = false;
169 <purpose>Determine if the current script should be exited.</purpose>
170 <usage>Check this variable after calling the
171 <functionlink>Process</functionlink> function and exit your script
172 immediately if the variable is set to
173 <booleanvalue>1</booleanvalue>.</usage>
183 <name>debug_output</name>
187 <purpose>Capture the debug output generated by the class</purpose>
188 <usage>Inspect this variable if you need to see what happened during
189 the class function calls.</usage>
194 var $debug_output = '';
199 <name>debug_prefix</name>
201 <value>OAuth client: </value>
203 <purpose>Mark the lines of the debug output to identify actions
204 performed by this class.</purpose>
205 <usage>Change this variable if you prefer the debug output lines to
206 be prefixed with a different text.</usage>
211 var $debug_prefix = 'OAuth client: ';
220 <purpose>Identify the type of OAuth server to access.</purpose>
221 <usage>The class provides built-in support to several types of OAuth
222 servers. This means that the class can automatically initialize
223 several configuration variables just by setting this server
224 variable.<paragraphbreak />
225 Currently it supports the following servers:
226 <stringvalue>Bitbucket</stringvalue>,
227 <stringvalue>Box</stringvalue>,
228 <stringvalue>Dropbox</stringvalue>,
229 <stringvalue>Eventful</stringvalue>,
230 <stringvalue>Facebook</stringvalue>,
231 <stringvalue>Fitbit</stringvalue>,
232 <stringvalue>Flickr</stringvalue>,
233 <stringvalue>Foursquare</stringvalue>,
234 <stringvalue>github</stringvalue>,
235 <stringvalue>Google</stringvalue>,
236 <stringvalue>Instagram</stringvalue>,
237 <stringvalue>LinkedIn</stringvalue>,
238 <stringvalue>Microsoft</stringvalue>,
239 <stringvalue>Scoop.it</stringvalue>,
240 <stringvalue>StockTwits</stringvalue>,
241 <stringvalue>Tumblr</stringvalue>,
242 <stringvalue>Twitter</stringvalue>,
243 <stringvalue>XING</stringvalue> and
244 <stringvalue>Yahoo</stringvalue>. Please contact the author if you
245 would like to ask to add built-in support for other types of OAuth
246 servers.<paragraphbreak />
247 If you want to access other types of OAuth servers that are not
248 yet supported, set this variable to an empty string and configure
249 other variables with values specific to those servers.</usage>
259 <name>request_token_url</name>
263 <purpose>URL of the OAuth server to request the initial token for
264 OAuth 1.0 and 1.0a servers.</purpose>
265 <usage>Set this variable to the OAuth request token URL when you are
266 not accessing one of the built-in supported OAuth
267 servers.<paragraphbreak />
268 For OAuth 1.0 and 1.0a servers, the request token URL can have
269 certain marks that will act as template placeholders which will be
270 replaced with given values before requesting the authorization
271 token. Currently it supports the following placeholder
272 marks:<paragraphbreak />
273 {SCOPE} - scope of the requested permissions to the granted by the
274 OAuth server with the user permissions</usage>
279 var $request_token_url = '';
284 <name>dialog_url</name>
288 <purpose>URL of the OAuth server to redirect the browser so the user
289 can grant access to your application.</purpose>
290 <usage>Set this variable to the OAuth request token URL when you are
291 not accessing one of the built-in supported OAuth servers.<paragraphbreak />
292 For certain servers, the dialog URL can have certain marks that
293 will act as template placeholders which will be replaced with
294 values defined before redirecting the users browser. Currently it
295 supports the following placeholder marks:<paragraphbreak />
296 {REDIRECT_URI} - URL to redirect when returning from the OAuth
297 server authorization page<paragraphbreak />
298 {CLIENT_ID} - client application identifier registered at the
299 server<paragraphbreak />
300 {SCOPE} - scope of the requested permissions to the granted by the
301 OAuth server with the user permissions<paragraphbreak />
302 {STATE} - identifier of the OAuth session state</usage>
307 var $dialog_url = '';
312 <name>offline_dialog_url</name>
316 <purpose>URL of the OAuth server to redirect the browser so the user
317 can grant access to your application when offline access is
319 <usage>Set this variable to the OAuth request token URL when you are
320 not accessing one of the built-in supported OAuth servers and the
321 OAuth server supports offline access.<paragraphbreak />
322 It should have the same format as the
323 <variablelink>dialog_url</variablelink> variable.</usage>
328 var $offline_dialog_url = '';
333 <name>append_state_to_redirect_uri</name>
337 <purpose>Pass the OAuth session state in a variable with a different
338 name to work around implementation bugs of certain OAuth
340 <usage>Set this variable when you are not accessing one of the
341 built-in supported OAuth servers if the OAuth server has a bug
342 that makes it not pass back the OAuth state identifier in a
343 request variable named state.</usage>
348 var $append_state_to_redirect_uri = '';
353 <name>access_token_url</name>
357 <purpose>OAuth server URL that will return the access token
359 <usage>Set this variable to the OAuth access token URL when you are
360 not accessing one of the built-in supported OAuth servers.</usage>
365 var $access_token_url = '';
371 <name>oauth_version</name>
375 <purpose>Version of the protocol version supported by the OAuth
377 <usage>Set this variable to the OAuth server protocol version when
378 you are not accessing one of the built-in supported OAuth
384 var $oauth_version = '2.0';
389 <name>url_parameters</name>
393 <purpose>Determine if the API call parameters should be moved to the
395 <usage>Set this variable to <booleanvalue>1</booleanvalue> if the
396 API you need to call requires that the call parameters always be
397 passed via the API URL.</usage>
402 var $url_parameters = false;
407 <name>authorization_header</name>
411 <purpose>Determine if the OAuth parameters should be passed via HTTP
412 Authorization request header.</purpose>
413 <usage>Set this variable to <booleanvalue>1</booleanvalue> if the
414 OAuth server requires that the OAuth parameters be passed using
415 the HTTP Authorization instead of the request URI parameters.</usage>
420 var $authorization_header = true;
425 <name>token_request_method</name>
429 <purpose>Define the HTTP method that should be used to request
430 tokens from the server.</purpose>
431 <usage>Set this variable to <stringvalue>POST</stringvalue> if the
432 OAuth server does not support requesting tokens using the HTTP GET
438 var $token_request_method = 'GET';
443 <name>signature_method</name>
445 <value>HMAC-SHA1</value>
447 <purpose>Define the method to generate the signature for API request
448 parameters values.</purpose>
449 <usage>Currently it supports <stringvalue>PLAINTEXT</stringvalue>
450 and <stringvalue>HMAC-SHA1</stringvalue>.</usage>
455 var $signature_method = 'HMAC-SHA1';
460 <name>redirect_uri</name>
464 <purpose>URL of the current script page that is calling this
466 <usage>Set this variable to the current script page URL before
467 proceeding the the OAuth authorization process.</usage>
472 var $redirect_uri = '';
477 <name>client_id</name>
481 <purpose>Identifier of your application registered with the OAuth
483 <usage>Set this variable to the application identifier that is
484 provided by the OAuth server when you register the
495 <name>client_secret</name>
499 <purpose>Secret value assigned to your application when it is
500 registered with the OAuth server.</purpose>
501 <usage>Set this variable to the application secret that is provided
502 by the OAuth server when you register the application.</usage>
507 var $client_secret = '';
516 <purpose>Permissions that your application needs to call the OAuth
517 server APIs</purpose>
518 <usage>Check the documentation of the APIs that your application
519 needs to call to set this variable with the identifiers of the
520 permissions that the user needs to grant to your application.</usage>
534 <purpose>Specify whether it will be necessary to call the API when
535 the user is not present and the server supports renewing expired
536 access tokens using refresh tokens.</purpose>
537 <usage>Set this variable to <booleanvalue>1</booleanvalue> if the
538 server supports renewing expired tokens automatically when the
539 user is not present.</usage>
544 var $offline = false;
549 <name>access_token</name>
553 <purpose>Access token obtained from the OAuth server</purpose>
554 <usage>Check this variable to get the obtained access token upon
555 successful OAuth authorization.</usage>
560 var $access_token = '';
565 <name>access_token_secret</name>
569 <purpose>Access token secret obtained from the OAuth server</purpose>
570 <usage>If the OAuth protocol version is 1.0 or 1.0a, check this
571 variable to get the obtained access token secret upon successful
572 OAuth authorization.</usage>
577 var $access_token_secret = '';
582 <name>access_token_expiry</name>
586 <purpose>Timestamp of the expiry of the access token obtained from
587 the OAuth server.</purpose>
588 <usage>Check this variable to get the obtained access token expiry
589 time upon successful OAuth authorization. If this variable is
590 empty, that means no expiry time was set.</usage>
595 var $access_token_expiry = '';
600 <name>access_token_type</name>
604 <purpose>Type of access token obtained from the OAuth server.</purpose>
605 <usage>Check this variable to get the obtained access token type
606 upon successful OAuth authorization.</usage>
611 var $access_token_type = '';
616 <name>refresh_token</name>
620 <purpose>Refresh token obtained from the OAuth server</purpose>
621 <usage>Check this variable to get the obtained refresh token upon
622 successful OAuth authorization.</usage>
627 var $refresh_token = '';
632 <name>access_token_error</name>
636 <purpose>Error message returned when a call to the API fails.</purpose>
637 <usage>Check this variable to determine if there was an error while
638 calling the Web services API when using the
639 <functionlink>CallAPI</functionlink> function.</usage>
644 var $access_token_error = '';
649 <name>authorization_error</name>
653 <purpose>Error message returned when it was not possible to obtain
654 an OAuth access token</purpose>
655 <usage>Check this variable to determine if there was an error while
656 trying to obtain the OAuth access token.</usage>
661 var $authorization_error = '';
666 <name>response_status</name>
670 <purpose>HTTP response status returned by the server when calling an
672 <usage>Check this variable after calling the
673 <functionlink>CallAPI</functionlink> function if the API calls and you
674 need to process the error depending the response status.
675 <integervalue>200</integervalue> means no error.
676 <integervalue>0</integervalue> means the server response was not
682 var $response_status = 0;
684 var $oauth_user_agent = 'PHP-OAuth-API (http://www.phpclasses.org/oauth-api $Revision: 1.58 $)';
685 var $session_started = false;
687 Function SetError($error)
689 $this->error = $error;
691 $this->OutputDebug('Error: '.$error);
695 Function SetPHPError($error, &$php_error_message)
697 if(IsSet($php_error_message)
698 && strlen($php_error_message))
699 $error.=": ".$php_error_message;
700 return($this->SetError($error));
703 Function OutputDebug($message)
707 $message = $this->debug_prefix.$message;
708 $this->debug_output .= $message."\n";;
714 Function GetRequestTokenURL(&$request_token_url)
716 $request_token_url = $this->request_token_url;
720 Function GetDialogURL(&$url, $redirect_uri = '', $state = '')
722 $url = (($this->offline && strlen($this->offline_dialog_url)) ? $this->offline_dialog_url : $this->dialog_url);
723 if(strlen($url) === 0)
724 return $this->SetError('the dialog URL '.($this->offline ? 'for offline access ' : '').'is not defined for this server');
726 '{REDIRECT_URI}', UrlEncode($redirect_uri), str_replace(
727 '{STATE}', UrlEncode($state), str_replace(
728 '{CLIENT_ID}', UrlEncode($this->client_id), str_replace(
729 '{SCOPE}', UrlEncode($this->scope),
734 Function GetAccessTokenURL(&$access_token_url)
736 $access_token_url = $this->access_token_url;
740 Function GetStoredState(&$state)
742 if(!$this->session_started)
744 if(!function_exists('session_start'))
745 return $this->SetError('Session variables are not accessible in this PHP environment');
747 if(IsSet($_SESSION['OAUTH_STATE']))
748 $state = $_SESSION['OAUTH_STATE'];
750 $state = $_SESSION['OAUTH_STATE'] = time().'-'.substr(md5(rand().time()), 0, 6);
754 Function GetRequestState(&$state)
756 $check = (strlen($this->append_state_to_redirect_uri) ? $this->append_state_to_redirect_uri : 'state');
757 $state = (IsSet($_GET[$check]) ? $_GET[$check] : null);
761 Function GetRequestCode(&$code)
763 $code = (IsSet($_GET['code']) ? $_GET['code'] : null);
767 Function GetRequestError(&$error)
769 $error = (IsSet($_GET['error']) ? $_GET['error'] : null);
773 Function GetRequestDenied(&$denied)
775 $denied = (IsSet($_GET['denied']) ? $_GET['denied'] : null);
779 Function GetRequestToken(&$token, &$verifier)
781 $token = (IsSet($_GET['oauth_token']) ? $_GET['oauth_token'] : null);
782 $verifier = (IsSet($_GET['oauth_verifier']) ? $_GET['oauth_verifier'] : null);
786 Function GetRedirectURI(&$redirect_uri)
788 if(strlen($this->redirect_uri))
789 $redirect_uri = $this->redirect_uri;
791 $redirect_uri = 'http://'.$_SERVER['HTTP_HOST'].$_SERVER['REQUEST_URI'];
798 <name>StoreAccessToken</name>
801 <purpose>Store the values of the access token when it is succefully
802 retrieved from the OAuth server.</purpose>
803 <usage>This function is meant to be only be called from inside the
804 class. By default it stores access tokens in a session variable
805 named <stringvalue>OAUTH_ACCESS_TOKEN</stringvalue>.<paragraphbreak />
806 Actual implementations should create a sub-class and override this
807 function to make the access token values be stored in other types
808 of containers, like for instance databases.</usage>
809 <returnvalue>This function should return
810 <booleanvalue>1</booleanvalue> if the access token was stored
811 successfully.</returnvalue>
814 <name>access_token</name>
817 <purpose>Associative array with properties of the access token.
818 The array may have set the following
819 properties:<paragraphbreak />
820 <stringvalue>value</stringvalue>: string value of the access
821 token<paragraphbreak />
822 <stringvalue>authorized</stringvalue>: boolean value that
823 determines if the access token was obtained
824 successfully<paragraphbreak />
825 <stringvalue>expiry</stringvalue>: (optional) timestamp in ISO
826 format relative to UTC time zone of the access token expiry
827 time<paragraphbreak />
828 <stringvalue>type</stringvalue>: (optional) type of OAuth token
829 that may determine how it should be used when sending API call
830 requests.<paragraphbreak />
831 <stringvalue>refresh</stringvalue>: (optional) token that some
832 servers may set to allowing refreshing access tokens when they
839 Function StoreAccessToken($access_token)
841 if(!$this->session_started)
843 if(!function_exists('session_start'))
844 return $this->SetError('Session variables are not accessible in this PHP environment');
846 $_SESSION['OAUTH_ACCESS_TOKEN'][$this->access_token_url] = $access_token;
859 <name>GetAccessToken</name>
862 <purpose>Retrieve the OAuth access token if it was already
863 previously stored by the
864 <functionlink>StoreAccessToken</functionlink> function.</purpose>
865 <usage>This function is meant to be only be called from inside the
866 class. By default it retrieves access tokens stored in a session
868 <stringvalue>OAUTH_ACCESS_TOKEN</stringvalue>.<paragraphbreak />
869 Actual implementations should create a sub-class and override this
870 function to retrieve the access token values from other types of
871 containers, like for instance databases.</usage>
872 <returnvalue>This function should return
873 <booleanvalue>1</booleanvalue> if the access token was retrieved
874 successfully.</returnvalue>
877 <name>access_token</name>
881 <purpose>Return the properties of the access token in an
882 associative array. If the access token was not yet stored, it
883 returns an empty array. Otherwise, the properties it may return
884 are the same that may be passed to the
885 <functionlink>StoreAccessToken</functionlink>.</purpose>
891 Function GetAccessToken(&$access_token)
893 if(!$this->session_started)
895 if(!function_exists('session_start'))
896 return $this->SetError('Session variables are not accessible in this PHP environment');
898 return($this->SetPHPError('it was not possible to start the PHP session', $php_error_message));
899 $this->session_started = true;
901 if(IsSet($_SESSION['OAUTH_ACCESS_TOKEN'][$this->access_token_url]))
902 $access_token = $_SESSION['OAUTH_ACCESS_TOKEN'][$this->access_token_url];
904 $access_token = array();
917 <name>ResetAccessToken</name>
920 <purpose>Reset the access token to a state back when the user has
921 not yet authorized the access to the OAuth server API.</purpose>
922 <usage>Call this function if for some reason the token to access
923 the API was revoked and you need to ask the user to authorize
924 the access again.<paragraphbreak />
925 By default the class stores and retrieves access tokens in a
926 session variable named
927 <stringvalue>OAUTH_ACCESS_TOKEN</stringvalue>.<paragraphbreak />
928 This function must be called when the user is accessing your site
929 pages, so it can reset the information stored in session variables
930 that cache the state of a previously retrieved access
931 token.<paragraphbreak />
932 Actual implementations should create a sub-class and override this
933 function to reset the access token state when it is stored in
934 other types of containers, like for instance databases.</usage>
935 <returnvalue>This function should return
936 <booleanvalue>1</booleanvalue> if the access token was resetted
937 successfully.</returnvalue>
942 Function ResetAccessToken()
945 $this->OutputDebug('Resetting the access token status for OAuth server located at '.$this->access_token_url);
946 if(!$this->session_started)
948 if(!function_exists('session_start'))
949 return $this->SetError('Session variables are not accessible in this PHP environment');
951 return($this->SetPHPError('it was not possible to start the PHP session', $php_error_message));
953 $this->session_started = true;
954 if(IsSet($_SESSION['OAUTH_ACCESS_TOKEN'][$this->access_token_url]))
955 Unset($_SESSION['OAUTH_ACCESS_TOKEN'][$this->access_token_url]);
965 Function Encode($value)
967 return(is_array($value) ? $this->EncodeArray($value) : str_replace('%7E', '~', str_replace('+',' ', RawURLEncode($value))));
970 Function EncodeArray($array)
972 foreach($array as $key => $value)
973 $array[$key] = $this->Encode($value);
977 Function HMAC($function, $data, $key)
986 $this->OutputDebug($function.' is not a supported an HMAC hash type');
989 if(strlen($key) > 64)
990 $key = pack($pack, $function($key));
991 if(strlen($key) < 64)
992 $key = str_pad($key, 64, "\0");
993 return(pack($pack, $function((str_repeat("\x5c", 64) ^ $key).pack($pack, $function((str_repeat("\x36", 64) ^ $key).$data)))));
996 Function SendAPIRequest($url, $method, $parameters, $oauth, $options, &$response)
998 $this->response_status = 0;
999 $http = new http_class;
1000 $http->debug = ($this->debug && $this->debug_http);
1001 $http->timeout = 30;
1002 $http->data_timeout = 60;
1003 $http->log_debug = true;
1004 $http->sasl_authenticate = 0;
1005 $http->user_agent = $this->oauth_user_agent;
1006 $http->redirection_limit = (IsSet($options['FollowRedirection']) ? intval($options['FollowRedirection']) : 0);
1007 $http->follow_redirect = ($http->redirection_limit != 0);
1009 $this->OutputDebug('Accessing the '.$options['Resource'].' at '.$url);
1010 $post_files = array();
1011 $method = strtoupper($method);
1012 $authorization = '';
1013 $type = (IsSet($options['RequestContentType']) ? strtolower(trim(strtok($options['RequestContentType'], ';'))) : 'application/x-www-form-urlencoded');
1017 'oauth_consumer_key'=>$this->client_id,
1018 //'oauth_nonce'=>md5(uniqid(rand(), true)),
1019 'oauth_nonce'=>sha1(uniqid(mt_rand(), true).uniqid(mt_rand(), true)),
1020 'oauth_signature_method'=>$this->signature_method,
1021 'oauth_timestamp'=>time(),
1022 'oauth_version'=>'1.0',
1024 $files = (IsSet($options['Files']) ? $options['Files'] : array());
1027 foreach($files as $name => $value)
1029 if(!IsSet($parameters[$name]))
1030 return($this->SetError('it was specified an file parameters named '.$name));
1032 switch(IsSet($value['Type']) ? $value['Type'] : 'FileName')
1035 $file['FileName'] = $parameters[$name];
1038 $file['Data'] = $parameters[$name];
1041 return($this->SetError($value['Type'].' is not a valid type for file '.$name));
1043 $file['ContentType'] = (IsSet($value['Content-Type']) ? $value['Content-Type'] : 'automatic/name');
1044 $post_files[$name] = $file;
1046 UnSet($parameters[$name]);
1047 if($method !== 'POST')
1049 $this->OutputDebug('For uploading files the method should be POST not '.$method);
1052 if($type !== 'multipart/form-data')
1054 if(IsSet($options['RequestContentType']))
1055 return($this->SetError('the request content type for uploading files should be multipart/form-data'));
1056 $type = 'multipart/form-data';
1058 $value_parameters = array();
1062 if($this->url_parameters
1063 && $type === 'application/x-www-form-urlencoded'
1064 && count($parameters))
1066 $first = (strpos($url, '?') === false);
1067 foreach($parameters as $parameter => $value)
1069 $url .= ($first ? '?' : '&').UrlEncode($parameter).'='.UrlEncode($value);
1072 $parameters = array();
1074 $value_parameters = ($type !== 'application/x-www-form-urlencoded' ? array() : $parameters);
1076 $values = array_merge($values, $oauth, $value_parameters);
1077 $key = $this->Encode($this->client_secret).'&'.$this->Encode($this->access_token_secret);
1078 switch($this->signature_method)
1081 $values['oauth_signature'] = $key;
1084 $uri = strtok($url, '?');
1085 $sign = $method.'&'.$this->Encode($uri).'&';
1087 $sign_values = $values;
1088 $u = parse_url($url);
1089 if(IsSet($u['query']))
1091 parse_str($u['query'], $q);
1092 foreach($q as $parameter => $value)
1093 $sign_values[$parameter] = $value;
1095 KSort($sign_values);
1096 foreach($sign_values as $parameter => $value)
1098 $sign .= $this->Encode(($first ? '' : '&').$parameter.'='.$this->Encode($value));
1101 $values['oauth_signature'] = base64_encode($this->HMAC('sha1', $sign, $key));
1104 return $this->SetError($this->signature_method.' signature method is not yet supported');
1106 if($this->authorization_header)
1108 $authorization = 'OAuth';
1110 foreach($values as $parameter => $value)
1112 $authorization .= ($first ? ' ' : ',').$parameter.'="'.$this->Encode($value).'"';
1118 if($method === 'GET'
1119 || (IsSet($options['PostValuesInURI'])
1120 && $options['PostValuesInURI']))
1122 $first = (strcspn($url, '?') == strlen($url));
1123 foreach($values as $parameter => $value)
1125 $url .= ($first ? '?' : '&').$parameter.'='.$this->Encode($value);
1128 $post_values = array();
1131 $post_values = $values;
1134 if(strlen($error = $http->GetRequestArguments($url, $arguments)))
1135 return($this->SetError('it was not possible to open the '.$options['Resource'].' URL: '.$error));
1136 if(strlen($error = $http->Open($arguments)))
1137 return($this->SetError('it was not possible to open the '.$options['Resource'].' URL: '.$error));
1138 if(count($post_files))
1139 $arguments['PostFiles'] = $post_files;
1140 $arguments['RequestMethod'] = $method;
1143 case 'application/x-www-form-urlencoded':
1144 case 'multipart/form-data':
1145 if(IsSet($options['RequestBody']))
1146 return($this->SetError('the request body is defined automatically from the parameters'));
1147 $arguments['PostValues'] = $parameters;
1149 case 'application/json':
1150 $arguments['Headers']['Content-Type'] = $options['RequestContentType'];
1151 if(!IsSet($options['RequestBody']))
1153 $arguments['Body'] = json_encode($parameters);
1157 if(!IsSet($options['RequestBody']))
1158 return($this->SetError('it was not specified the body value of the of the API call request'));
1159 $arguments['Headers']['Content-Type'] = $options['RequestContentType'];
1160 $arguments['Body'] = $options['RequestBody'];
1163 $arguments['Headers']['Accept'] = (IsSet($options['Accept']) ? $options['Accept'] : '*/*');
1164 if(strlen($authorization))
1165 $arguments['Headers']['Authorization'] = $authorization;
1166 if(strlen($error = $http->SendRequest($arguments))
1167 || strlen($error = $http->ReadReplyHeaders($headers)))
1170 return($this->SetError('it was not possible to retrieve the '.$options['Resource'].': '.$error));
1172 $error = $http->ReadWholeReplyBody($data);
1176 return($this->SetError('it was not possible to access the '.$options['Resource'].': '.$error));
1178 $this->response_status = intval($http->response_status);
1179 $content_type = (IsSet($options['ResponseContentType']) ? $options['ResponseContentType'] : (IsSet($headers['content-type']) ? strtolower(trim(strtok($headers['content-type'], ';'))) : 'unspecified'));
1180 switch($content_type)
1182 case 'text/javascript':
1183 case 'application/json':
1184 if(!function_exists('json_decode'))
1185 return($this->SetError('the JSON extension is not available in this PHP setup'));
1186 $object = json_decode($data);
1187 switch(GetType($object))
1190 if(!IsSet($options['ConvertObjects'])
1191 || !$options['ConvertObjects'])
1192 $response = $object;
1195 $response = array();
1196 foreach($object as $property => $value)
1197 $response[$property] = $value;
1201 $response = $object;
1205 return($this->SetError('it was not returned a valid JSON definition of the '.$options['Resource'].' values'));
1206 $response = $object;
1210 case 'application/x-www-form-urlencoded':
1213 parse_str($data, $response);
1219 if($this->response_status >= 200
1220 && $this->response_status < 300)
1221 $this->access_token_error = '';
1224 $this->access_token_error = 'it was not possible to access the '.$options['Resource'].': it was returned an unexpected response status '.$http->response_status.' Response: '.$data;
1226 $this->OutputDebug('Could not retrieve the OAuth access. Error: '.$this->access_token_error);
1227 if(IsSet($options['FailOnAccessError'])
1228 && $options['FailOnAccessError'])
1230 $this->error = $this->access_token_error;
1237 Function ProcessToken($code, $refresh)
1242 'client_id'=>$this->client_id,
1243 'client_secret'=>$this->client_secret,
1244 'refresh_token'=>$this->refresh_token,
1245 'grant_type'=>'refresh_token'
1250 if(!$this->GetRedirectURI($redirect_uri))
1254 'client_id'=>$this->client_id,
1255 'client_secret'=>$this->client_secret,
1256 'redirect_uri'=>$redirect_uri,
1257 'grant_type'=>'authorization_code'
1260 if(!$this->GetAccessTokenURL($url))
1262 if(!$this->SendAPIRequest($url, 'POST', $values, null, array('Resource'=>'OAuth '.($refresh ? 'refresh' : 'access').' token', 'ConvertObjects'=>true), $response))
1264 if(strlen($this->access_token_error))
1266 $this->authorization_error = $this->access_token_error;
1269 if(!IsSet($response['access_token']))
1271 if(IsSet($response['error']))
1273 $this->authorization_error = 'it was not possible to retrieve the access token: it was returned the error: '.$response['error'];
1276 return($this->SetError('OAuth server did not return the access token'));
1278 $access_token = array(
1279 'value'=>$this->access_token = $response['access_token'],
1283 $this->OutputDebug('Access token: '.$this->access_token);
1284 if(IsSet($response['expires'])
1285 || IsSet($response['expires_in']))
1287 $expires = (IsSet($response['expires']) ? $response['expires'] : $response['expires_in']);
1288 if(strval($expires) !== strval(intval($expires))
1290 return($this->SetError('OAuth server did not return a supported type of access token expiry time'));
1291 $this->access_token_expiry = gmstrftime('%Y-%m-%d %H:%M:%S', time() + $expires);
1293 $this->OutputDebug('Access token expiry: '.$this->access_token_expiry.' UTC');
1294 $access_token['expiry'] = $this->access_token_expiry;
1297 $this->access_token_expiry = '';
1298 if(IsSet($response['token_type']))
1300 $this->access_token_type = $response['token_type'];
1302 $this->OutputDebug('Access token type: '.$this->access_token_type);
1303 $access_token['type'] = $this->access_token_type;
1306 $this->access_token_type = '';
1308 $response['refresh_token'] = $this->refresh_token;
1309 elseif(IsSet($response['refresh_token']))
1311 $this->refresh_token = $response['refresh_token'];
1313 $this->OutputDebug('Refresh token: '.$this->refresh_token);
1314 $access_token['refresh'] = $this->refresh_token;
1317 $this->refresh_token = '';
1318 if(!$this->StoreAccessToken($access_token))
1323 Function RetrieveToken(&$valid)
1326 if(!$this->GetAccessToken($access_token))
1328 if(IsSet($access_token['value']))
1330 $this->access_token_expiry = '';
1331 if(IsSet($access_token['expiry'])
1332 && strcmp($this->access_token_expiry = $access_token['expiry'], gmstrftime('%Y-%m-%d %H:%M:%S')) < 0)
1334 $this->access_token = '';
1336 $this->OutputDebug('The OAuth access token expired in '.$this->access_token_expiry);
1340 $this->access_token = $access_token['value'];
1341 if(IsSet($access_token['type']))
1342 $this->access_token_type = $access_token['type'];
1344 $this->access_token_type = '';
1346 $this->OutputDebug('The OAuth access token '.$this->access_token.' is valid');
1347 if(strlen($this->access_token_type)
1349 $this->OutputDebug('The OAuth access token is of type '.$this->access_token_type);
1350 if(IsSet($access_token['refresh']))
1351 $this->refresh_token = $access_token['refresh'];
1353 $this->refresh_token = '';
1362 <name>CallAPI</name>
1363 <type>BOOLEAN</type>
1365 <purpose>Send a HTTP request to the Web services API using a
1366 previously obtained authorization token via OAuth.</purpose>
1367 <usage>This function can be used to call an API after having
1368 previously obtained an access token through the OAuth protocol
1369 using the <functionlink>Process</functionlink> function, or by
1370 directly setting the variables
1371 <variablelink>access_token</variablelink>, as well as
1372 <variablelink>access_token_secret</variablelink> in case of using
1373 OAuth 1.0 or 1.0a services.</usage>
1374 <returnvalue>This function returns <booleanvalue>1</booleanvalue> if
1375 the call was done successfully.</returnvalue>
1381 <purpose>URL of the API where the HTTP request will be sent.</purpose>
1388 <purpose>HTTP method that will be used to send the request. It can
1389 be <stringvalue>GET</stringvalue>,
1390 <stringvalue>POST</stringvalue>,
1391 <stringvalue>DELETE</stringvalue>, <stringvalue>PUT</stringvalue>,
1396 <name>parameters</name>
1399 <purpose>Associative array with the names and values of the API
1400 call request parameters.</purpose>
1404 <name>options</name>
1407 <purpose>Associative array with additional options to configure
1408 the request. Currently it supports the following
1409 options:<paragraphbreak />
1410 <stringvalue>2Legged</stringvalue>: boolean option that
1411 determines if the API request should be 2 legged. The default
1412 value is <tt><booleanvalue>0</booleanvalue></tt>.<paragraphbreak />
1413 <stringvalue>Accept</stringvalue>: content type value of the
1414 Accept HTTP header to be sent in the API call HTTP request.
1415 Some APIs require that a certain value be sent to specify
1416 which version of the API is being called. The default value is
1417 <stringvalue>*/*</stringvalue>.<paragraphbreak />
1418 <stringvalue>ConvertObjects</stringvalue>: boolean option that
1419 determines if objects should be converted into arrays when the
1420 response is returned in JSON format. The default value is
1421 <booleanvalue>0</booleanvalue>.<paragraphbreak />
1422 <stringvalue>FailOnAccessError</stringvalue>: boolean option
1423 that determines if this functions should fail when the server
1424 response status is not between 200 and 299. The default value
1425 is <booleanvalue>0</booleanvalue>.<paragraphbreak />
1426 <stringvalue>Files</stringvalue>: associative array with
1427 details of the parameters that must be passed as file uploads.
1428 The array indexes must have the same name of the parameters
1429 to be sent as files. The respective array entry values must
1430 also be associative arrays with the parameters for each file.
1431 Currently it supports the following parameters:<paragraphbreak />
1432 - <tt>Type</tt> - defines how the parameter value should be
1433 treated. It can be <tt>'FileName'</tt> if the parameter value is
1434 is the name of a local file to be uploaded. It may also be
1435 <tt>'Data'</tt> if the parameter value is the actual data of
1436 the file to be uploaded.<paragraphbreak />
1437 - Default: <tt>'FileName'</tt><paragraphbreak />
1438 - <tt>ContentType</tt> - MIME value of the content type of the
1439 file. It can be <tt>'automatic/name'</tt> if the content type
1440 should be determine from the file name extension.<paragraphbreak />
1441 - Default: <tt>'automatic/name'</tt><paragraphbreak />
1442 <stringvalue>PostValuesInURI</stringvalue>: boolean option to
1443 determine that a POST request should pass the request values
1444 in the URI. The default value is
1445 <booleanvalue>0</booleanvalue>.<paragraphbreak />
1446 <stringvalue>FollowRedirection</stringvalue>: limit number of
1447 times that HTTP response redirects will be followed. If it is
1448 set to <integervalue>0</integervalue>, redirection responses
1449 fail in error. The default value is
1450 <integervalue>0</integervalue>.<paragraphbreak />
1451 <stringvalue>RequestBody</stringvalue>: request body data of a
1452 custom type. The <stringvalue>RequestContentType</stringvalue>
1453 option must be specified, so the
1454 <stringvalue>RequestBody</stringvalue> option is considered.<paragraphbreak />
1455 <stringvalue>RequestContentType</stringvalue>: content type that
1456 should be used to send the request values. It can be either
1457 <stringvalue>application/x-www-form-urlencoded</stringvalue>
1458 for sending values like from Web forms, or
1459 <stringvalue>application/json</stringvalue> for sending the
1460 values encoded in JSON format. Other types are accepted if the
1461 <stringvalue>RequestBody</stringvalue> option is specified.
1462 The default value is
1463 <stringvalue>application/x-www-form-urlencoded</stringvalue>.<paragraphbreak />
1464 <stringvalue>RequestBody</stringvalue>: request body data of a
1465 custom type. The <stringvalue>RequestContentType</stringvalue>
1466 option must be specified, so the
1467 <stringvalue>RequestBody</stringvalue> option is considered.<paragraphbreak />
1468 <stringvalue>Resource</stringvalue>: string with a label that
1469 will be used in the error messages and debug log entries to
1470 identify what operation the request is performing. The default
1471 value is <stringvalue>API call</stringvalue>.<paragraphbreak />
1472 <stringvalue>ResponseContentType</stringvalue>: content type
1473 that should be considered when decoding the API request
1474 response. This overrides the <tt>Content-Type</tt> header
1475 returned by the server. If the content type is
1476 <stringvalue>application/x-www-form-urlencoded</stringvalue>
1477 the function will parse the data returning an array of
1478 key-value pairs. If the content type is
1479 <stringvalue>application/json</stringvalue> the response will
1480 be decode as a JSON-encoded data type. Other content type
1481 values will make the function return the original response
1482 value as it was returned from the server. The default value
1483 for this option is to use what the server returned in the
1484 <tt>Content-Type</tt> header.</purpose>
1488 <name>response</name>
1492 <purpose>Return the value of the API response. If the value is
1493 JSON encoded, this function will decode it and return the value
1494 converted to respective types. If the value is form encoded,
1495 this function will decode the response and return it as an
1496 array. Otherwise, the class will return the value as a
1503 Function CallAPI($url, $method, $parameters, $options, &$response)
1505 if(!IsSet($options['Resource']))
1506 $options['Resource'] = 'API call';
1507 if(!IsSet($options['ConvertObjects']))
1508 $options['ConvertObjects'] = false;
1509 if(strlen($this->access_token) === 0)
1511 if(!$this->RetrieveToken($valid))
1514 return $this->SetError('the access token is not set to a valid value');
1516 switch(intval($this->oauth_version))
1520 'oauth_token'=>((IsSet($options['2Legged']) && $options['2Legged']) ? '' : $this->access_token)
1525 if(strlen($this->access_token_expiry)
1526 && strcmp($this->access_token_expiry, gmstrftime('%Y-%m-%d %H:%M:%S')) <= 0)
1528 if(strlen($this->refresh_token) === 0)
1529 return($this->SetError('the access token expired and no refresh token is available'));
1532 $this->OutputDebug('The access token expired on '.$this->access_token_expiry);
1533 $this->OutputDebug('Refreshing the access token');
1535 if(!$this->ProcessToken(null, true))
1539 $url .= (strcspn($url, '?') < strlen($url) ? '&' : '?').'access_token='.UrlEncode($this->access_token);
1543 return($this->SetError($this->oauth_version.' is not a supported version of the OAuth protocol'));
1545 return($this->SendAPIRequest($url, $method, $parameters, $oauth, $options, $response));
1557 <name>Initialize</name>
1558 <type>BOOLEAN</type>
1560 <purpose>Initialize the class variables and internal state. It must
1561 be called before calling other class functions.</purpose>
1562 <usage>Set the <variablelink>server</variablelink> variable before
1563 calling this function to let it initialize the class variables to
1564 work with the specified server type. Alternatively, you can set
1565 other class variables manually to make it work with servers that
1566 are not yet built-in supported.</usage>
1567 <returnvalue>This function returns <booleanvalue>1</booleanvalue> if
1568 it was able to successfully initialize the class for the specified
1569 server type.</returnvalue>
1574 Function Initialize()
1576 if(strlen($this->server) === 0)
1578 $this->request_token_url = '';
1579 $this->append_state_to_redirect_uri = '';
1580 $this->authorization_header = true;
1581 $this->url_parameters = false;
1582 $this->token_request_method = 'GET';
1583 $this->signature_method = 'HMAC-SHA1';
1584 switch($this->server)
1587 $this->oauth_version = '1.0a';
1588 $this->request_token_url = 'https://bitbucket.org/!api/1.0/oauth/request_token';
1589 $this->dialog_url = 'https://bitbucket.org/!api/1.0/oauth/authenticate';
1590 $this->access_token_url = 'https://bitbucket.org/!api/1.0/oauth/access_token';
1591 $this->url_parameters = true;
1595 $this->oauth_version = '2.0';
1596 $this->dialog_url = 'https://www.box.com/api/oauth2/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}';
1597 $this->offline_dialog_url = 'https://www.box.com/api/oauth2/authorize?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&state={STATE}&access_type=offline&approval_prompt=force';
1598 $this->access_token_url = 'https://www.box.com/api/oauth2/token';
1602 $this->oauth_version = '1.0';
1603 $this->request_token_url = 'https://api.dropbox.com/1/oauth/request_token';
1604 $this->dialog_url = 'https://www.dropbox.com/1/oauth/authorize';
1605 $this->access_token_url = 'https://api.dropbox.com/1/oauth/access_token';
1606 $this->authorization_header = false;
1610 $this->oauth_version = '1.0a';
1611 $this->request_token_url = 'http://eventful.com/oauth/request_token';
1612 $this->dialog_url = 'http://eventful.com/oauth/authorize';
1613 $this->access_token_url = 'http://eventful.com/oauth/access_token';
1614 $this->authorization_header = false;
1615 $this->url_parameters = true;
1616 $this->token_request_method = 'POST';
1620 $this->oauth_version = '1.0a';
1621 $this->request_token_url = 'https://sandbox.evernote.com/oauth';
1622 $this->dialog_url = 'https://sandbox.evernote.com/OAuth.action';
1623 $this->access_token_url = 'https://sandbox.evernote.com/oauth';
1624 $this->url_parameters = true;
1625 $this->authorization_header = false;
1629 $this->oauth_version = '2.0';
1630 $this->dialog_url = 'https://www.facebook.com/dialog/oauth?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}&state={STATE}';
1631 $this->access_token_url = 'https://graph.facebook.com/oauth/access_token';
1635 $this->oauth_version = '1.0a';
1636 $this->request_token_url = 'http://api.fitbit.com/oauth/request_token';
1637 $this->dialog_url = 'http://api.fitbit.com/oauth/authorize';
1638 $this->access_token_url = 'http://api.fitbit.com/oauth/access_token';
1642 $this->oauth_version = '1.0a';
1643 $this->request_token_url = 'http://www.flickr.com/services/oauth/request_token';
1644 $this->dialog_url = 'http://www.flickr.com/services/oauth/authorize?perms={SCOPE}';
1645 $this->access_token_url = 'http://www.flickr.com/services/oauth/access_token';
1646 $this->authorization_header = false;
1650 $this->oauth_version = '2.0';
1651 $this->dialog_url = 'https://foursquare.com/oauth2/authorize?client_id={CLIENT_ID}&scope={SCOPE}&response_type=code&redirect_uri={REDIRECT_URI}&state={STATE}';
1652 $this->access_token_url = 'https://foursquare.com/oauth2/access_token';
1656 $this->oauth_version = '2.0';
1657 $this->dialog_url = 'https://github.com/login/oauth/authorize?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}&state={STATE}';
1658 $this->access_token_url = 'https://github.com/login/oauth/access_token';
1662 $this->oauth_version = '2.0';
1663 $this->dialog_url = 'https://accounts.google.com/o/oauth2/auth?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}&state={STATE}';
1664 $this->offline_dialog_url = 'https://accounts.google.com/o/oauth2/auth?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}&state={STATE}&access_type=offline&approval_prompt=force';
1665 $this->access_token_url = 'https://accounts.google.com/o/oauth2/token';
1669 $this->oauth_version = '2.0';
1670 $this->dialog_url ='https://api.instagram.com/oauth/authorize/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPE}&response_type=code&state={STATE}';
1671 $this->access_token_url = 'https://api.instagram.com/oauth/access_token';
1675 $this->oauth_version = '1.0a';
1676 $this->request_token_url = 'https://api.linkedin.com/uas/oauth/requestToken?scope={SCOPE}';
1677 $this->dialog_url = 'https://api.linkedin.com/uas/oauth/authenticate';
1678 $this->access_token_url = 'https://api.linkedin.com/uas/oauth/accessToken';
1679 $this->url_parameters = true;
1683 $this->oauth_version = '2.0';
1684 $this->dialog_url = 'https://login.live.com/oauth20_authorize.srf?client_id={CLIENT_ID}&scope={SCOPE}&response_type=code&redirect_uri={REDIRECT_URI}&state={STATE}';
1685 $this->access_token_url = 'https://login.live.com/oauth20_token.srf';
1688 case 'RightSignature':
1689 $this->oauth_version = '1.0a';
1690 $this->request_token_url = 'https://rightsignature.com/oauth/request_token';
1691 $this->dialog_url = 'https://rightsignature.com/oauth/authorize';
1692 $this->access_token_url = 'https://rightsignature.com/oauth/access_token';
1693 $this->authorization_header = false;
1697 $this->oauth_version = '1.0a';
1698 $this->request_token_url = 'https://www.scoop.it/oauth/request';
1699 $this->dialog_url = 'https://www.scoop.it/oauth/authorize';
1700 $this->access_token_url = 'https://www.scoop.it/oauth/access';
1701 $this->authorization_header = false;
1705 $this->oauth_version = '2.0';
1706 $this->dialog_url = 'https://api.stocktwits.com/api/2/oauth/authorize?client_id={CLIENT_ID}&response_type=code&redirect_uri={REDIRECT_URI}&scope={SCOPE}&state={STATE}';
1707 $this->access_token_url = 'https://api.stocktwits.com/api/2/oauth/token';
1711 $this->oauth_version = '1.0a';
1712 $this->request_token_url = 'http://www.tumblr.com/oauth/request_token';
1713 $this->dialog_url = 'http://www.tumblr.com/oauth/authorize';
1714 $this->access_token_url = 'http://www.tumblr.com/oauth/access_token';
1718 $this->oauth_version = '1.0a';
1719 $this->request_token_url = 'https://api.twitter.com/oauth/request_token';
1720 $this->dialog_url = 'https://api.twitter.com/oauth/authenticate';
1721 $this->access_token_url = 'https://api.twitter.com/oauth/access_token';
1722 $this->url_parameters = true;
1726 $this->oauth_version = '1.0a';
1727 $this->request_token_url = 'https://api.xing.com/v1/request_token';
1728 $this->dialog_url = 'https://api.xing.com/v1/authorize';
1729 $this->access_token_url = 'https://api.xing.com/v1/access_token';
1730 $this->authorization_header = false;
1734 $this->oauth_version = '1.0a';
1735 $this->request_token_url = 'https://api.login.yahoo.com/oauth/v2/get_request_token';
1736 $this->dialog_url = 'https://api.login.yahoo.com/oauth/v2/request_auth';
1737 $this->access_token_url = 'https://api.login.yahoo.com/oauth/v2/get_token';
1738 $this->authorization_header = false;
1742 return($this->SetError($this->server.' is not yet a supported type of OAuth server. Please contact the author Manuel Lemos <mlemos@acm.org> to request adding built-in support to this type of OAuth server.'));
1756 <name>Process</name>
1757 <type>BOOLEAN</type>
1759 <purpose>Process the OAuth protocol interaction with the OAuth
1761 <usage>Call this function when you need to retrieve the OAuth access
1762 token. Check the <variablelink>access_token</variablelink> to
1763 determine if the access token was obtained successfully.</usage>
1764 <returnvalue>This function returns <booleanvalue>1</booleanvalue> if
1765 the OAuth protocol was processed without errors.</returnvalue>
1772 switch(intval($this->oauth_version))
1775 $one_a = ($this->oauth_version === '1.0a');
1777 $this->OutputDebug('Checking the OAuth token authorization state');
1778 if(!$this->GetAccessToken($access_token))
1780 if(IsSet($access_token['authorized'])
1781 && IsSet($access_token['value']))
1783 $expired = (IsSet($access_token['expiry']) && strcmp($access_token['expiry'], gmstrftime('%Y-%m-%d %H:%M:%S')) <= 0);
1784 if(!$access_token['authorized']
1790 $this->OutputDebug('The OAuth token expired on '.$access_token['expiry'].'UTC');
1792 $this->OutputDebug('The OAuth token is not yet authorized');
1793 $this->OutputDebug('Checking the OAuth token and verifier');
1795 if(!$this->GetRequestToken($token, $verifier))
1799 && !IsSet($verifier)))
1801 if(!$this->GetRequestDenied($denied))
1804 && $denied === $access_token['value'])
1807 $this->OutputDebug('The authorization request was denied');
1808 $this->authorization_error = 'the request was denied';
1814 $this->OutputDebug('Reset the OAuth token state because token and verifier are not both set');
1815 $access_token = array();
1818 elseif($token !== $access_token['value'])
1821 $this->OutputDebug('Reset the OAuth token state because token does not match what as previously retrieved');
1822 $access_token = array();
1826 if(!$this->GetAccessTokenURL($url))
1829 'oauth_token'=>$token,
1832 $oauth['oauth_verifier'] = $verifier;
1833 $this->access_token_secret = $access_token['secret'];
1834 $options = array('Resource'=>'OAuth access token');
1835 $method = strtoupper($this->token_request_method);
1841 $options['PostValuesInURI'] = true;
1844 $this->error = $method.' is not a supported method to request tokens';
1847 if(!$this->SendAPIRequest($url, $method, array(), $oauth, $options, $response))
1849 if(strlen($this->access_token_error))
1851 $this->authorization_error = $this->access_token_error;
1854 if(!IsSet($response['oauth_token'])
1855 || !IsSet($response['oauth_token_secret']))
1857 $this->authorization_error= 'it was not returned the access token and secret';
1860 $access_token = array(
1861 'value'=>$response['oauth_token'],
1862 'secret'=>$response['oauth_token_secret'],
1865 if(IsSet($response['oauth_expires_in']))
1867 $expires = $response['oauth_expires_in'];
1868 if(strval($expires) !== strval(intval($expires))
1870 return($this->SetError('OAuth server did not return a supported type of access token expiry time'));
1871 $this->access_token_expiry = gmstrftime('%Y-%m-%d %H:%M:%S', time() + $expires);
1873 $this->OutputDebug('Access token expiry: '.$this->access_token_expiry.' UTC');
1874 $access_token['expiry'] = $this->access_token_expiry;
1877 $this->access_token_expiry = '';
1879 if(!$this->StoreAccessToken($access_token))
1882 $this->OutputDebug('The OAuth token was authorized');
1885 elseif($this->debug)
1886 $this->OutputDebug('The OAuth token was already authorized');
1887 if(IsSet($access_token['authorized'])
1888 && $access_token['authorized'])
1890 $this->access_token = $access_token['value'];
1891 $this->access_token_secret = $access_token['secret'];
1898 $this->OutputDebug('The OAuth access token is not set');
1899 $access_token = array();
1901 if(!IsSet($access_token['authorized']))
1904 $this->OutputDebug('Requesting the unauthorized OAuth token');
1905 if(!$this->GetRequestTokenURL($url))
1907 $url = str_replace('{SCOPE}', UrlEncode($this->scope), $url);
1908 if(!$this->GetRedirectURI($redirect_uri))
1911 'oauth_callback'=>$redirect_uri,
1913 $options = array('Resource'=>'OAuth request token');
1914 $method = strtoupper($this->token_request_method);
1920 $options['PostValuesInURI'] = true;
1923 $this->error = $method.' is not a supported method to request tokens';
1926 if(!$this->SendAPIRequest($url, $method, array(), $oauth, $options, $response))
1928 if(strlen($this->access_token_error))
1930 $this->authorization_error = $this->access_token_error;
1933 if(!IsSet($response['oauth_token'])
1934 || !IsSet($response['oauth_token_secret']))
1936 $this->authorization_error = 'it was not returned the requested token';
1939 $access_token = array(
1940 'value'=>$response['oauth_token'],
1941 'secret'=>$response['oauth_token_secret'],
1944 if(!$this->StoreAccessToken($access_token))
1947 if(!$this->GetDialogURL($url))
1949 $url .= (strpos($url, '?') === false ? '?' : '&').'oauth_token='.$access_token['value'];
1952 if(!$this->GetRedirectURI($redirect_uri))
1954 $url .= '&oauth_callback='.UrlEncode($redirect_uri);
1957 $this->OutputDebug('Redirecting to OAuth authorize page '.$url);
1958 Header('HTTP/1.0 302 OAuth Redirection');
1959 Header('Location: '.$url);
1965 $this->OutputDebug('Checking if OAuth access token was already retrieved from '.$this->access_token_url);
1966 if(!$this->RetrieveToken($valid))
1971 $this->OutputDebug('Checking the authentication state in URI '.$_SERVER['REQUEST_URI']);
1972 if(!$this->GetStoredState($stored_state))
1974 if(strlen($stored_state) == 0)
1975 return($this->SetError('it was not set the OAuth state'));
1976 if(!$this->GetRequestState($state))
1978 if($state === $stored_state)
1981 $this->OutputDebug('Checking the authentication code');
1982 if(!$this->GetRequestCode($code))
1984 if(strlen($code) == 0)
1986 if(!$this->GetRequestError($this->authorization_error))
1988 if(IsSet($this->authorization_error))
1991 $this->OutputDebug('Authorization failed with error code '.$this->authorization_error);
1992 switch($this->authorization_error)
1994 case 'invalid_request':
1995 case 'unauthorized_client':
1996 case 'access_denied':
1997 case 'unsupported_response_type':
1998 case 'invalid_scope':
1999 case 'server_error':
2000 case 'temporarily_unavailable':
2004 return($this->SetError('it was returned an unknown OAuth error code'));
2007 return($this->SetError('it was not returned the OAuth dialog code'));
2009 if(!$this->ProcessToken($code, false))
2014 if(!$this->GetRedirectURI($redirect_uri))
2016 if(strlen($this->append_state_to_redirect_uri))
2017 $redirect_uri .= (strpos($redirect_uri, '?') === false ? '?' : '&').$this->append_state_to_redirect_uri.'='.$stored_state;
2018 if(!$this->GetDialogURL($url, $redirect_uri, $stored_state))
2020 if(strlen($url) == 0)
2021 return($this->SetError('it was not set the OAuth dialog URL'));
2023 $this->OutputDebug('Redirecting to OAuth Dialog '.$url);
2024 Header('HTTP/1.0 302 OAuth Redirection');
2025 Header('Location: '.$url);
2031 return($this->SetError($this->oauth_version.' is not a supported version of the OAuth protocol'));
2045 <name>Finalize</name>
2046 <type>BOOLEAN</type>
2048 <purpose>Cleanup any resources that may have been used during the
2049 OAuth protocol processing or execution of API calls.</purpose>
2050 <usage>Always call this function as the last step after calling the
2051 functions <functionlink>Process</functionlink> or
2052 <functionlink>CallAPI</functionlink>.</usage>
2053 <returnvalue>This function returns <booleanvalue>1</booleanvalue> if
2054 the function cleaned up any resources successfully.</returnvalue>
2057 <name>success</name>
2058 <type>BOOLEAN</type>
2060 <purpose>Pass the last success state returned by the class or any
2061 external code processing the class function results.</purpose>
2067 Function Finalize($success)
2084 <purpose>Display the results of the OAuth protocol processing.</purpose>
2085 <usage>Only call this function if you are debugging the OAuth
2086 authorization process and you need to view what was its
2094 if(strlen($this->authorization_error)
2095 || strlen($this->access_token_error)
2096 || strlen($this->access_token))
2099 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2102 <title>OAuth client result</title>
2105 <h1>OAuth client result</h1>
2107 if(strlen($this->authorization_error))
2110 <p>It was not possible to authorize the application.<?php
2114 <br>Authorization error: <?php echo HtmlSpecialChars($this->authorization_error);
2119 elseif(strlen($this->access_token_error))
2122 <p>It was not possible to use the application access token.
2127 <br>Error: <?php echo HtmlSpecialChars($this->access_token_error);
2132 elseif(strlen($this->access_token))
2135 <p>The application authorization was obtained successfully.
2140 <br>Access token: <?php echo HtmlSpecialChars($this->access_token);
2141 if(IsSet($this->access_token_secret))
2144 <br>Access token secret: <?php echo HtmlSpecialChars($this->access_token_secret);
2149 if(strlen($this->access_token_expiry))
2152 <p>Access token expiry: <?php echo $this->access_token_expiry; ?> UTC</p>