Wiki

About

X-OAuth-PHP is a php xAuth and OAuth (1.0a) client and provider.

Creating a OAuth / xAuth client

You will need to create a OAuthClient, passing the signature used, the consumer key and secret and token and token secret (if needed)

$signature = new \Zeflasher\OAuth\SignatureMethods\OAuthSignatureMethodHmacSha1();
$oauth_client = new OAuthClient($signature, "consumer_key", "consumer_secret", "token_key", "token_secret");

Then you call the request method on the client as follow

/**   
 * return object is as follow
 * {
 * string header The response header
 * string body The response body
 * int http_code The Http response code
 * string last_url The last url called
 * }
 * @param string $url All the query string will be removed. Passed them in the param array
 * @param string $method GET, POST, PUT, DELETE, and any custom ones you would provide
 * @param array $parameters Array in the following format ['key' => value]
 * @param string $returnType Format we you are expecting the response (not implemented yet)
 * @param string $callbackUrl The callbackurl (optional)
 * @param string $verifier Any verifier (optional)
 * @param string $proxy Proxy to use
 * @return \stdClass
 */
$result = $oauth_client->request( "url", "POST", [], 'json', "callbackUrl", "verifier");

For an xAuth client you will add the xAuth parameters needed like this

$oauth_client->set_parameter(\Zeflasher\OAuth\X_AUTH_USERNAME, "username");
$oauth_client->set_parameter(\Zeflasher\OAuth\X_AUTH_PASSWORD, "password");
$oauth_client->set_parameter(\Zeflasher\OAuth\X_AUTH_MODE, \Zeflasher\OAuth\X_AUTH_MODE_VALUE);
$oauth_client->request(...);

Creating a OAuth / xAuth provider

The way and place you are storing the data for verification won't be covered here. It is up to you. That's mainly why I have develop this library.

X-OAuth-PHP provides a OAuthProvider class which will need be set up to be working. In all the following examples the code is made in a custom class extending the OAuthProvider (but you can use composition also)

Setting up the signature method used to create the signature

$hmac_method = new \Zeflasher\OAuth\SignatureMethods\OAuthSignatureMethodHmacSha1();
$this->add_signature_method($hmac_method);

Setting up the handlers for the different checks to be done

In the following example the 'check_consumer', 'check_timestamp', 'check_nonce' and 'check_token' are methods name. Those methods will be called when the provider will check the request is actually valid by verifying consumer, timestamp, nonce and token are correct.

//  setup check functions
$this->consumer_handler( array($this,'check_consumer') );
$this->timestamp_handler( array($this,'check_timestamp') );
$this->nonce_handler( array($this,'check_nonce') );
$this->token_handler( array($this,'check_token') );

Setting up for a request token

When you are requesting a request token:

the token will be removed from the required parameters (as it is not sent)
the callback will be added to the required parameters
the token will not be checked when validating the request (as there is no token to check). This is done internally by calling is_request_token(true)

All this is applied when calling the set_request_token_query() method.

Now that everything is set up you can check the request by calling the check_oauth_request() method and if valid generating a token and token secret (that you will have identified as request token in your db or files or ...)

//  we are using the oauth flow
$this->set_to_oauth_flow();

//  we are asking for a request token
$this->set_request_token_query();

//  check the request, this will call the check_consumer, check_timestamp, check_nonce, check_token method
$this->check_oauth_request();

//  generates the token and secret
$request_token_key = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));
$request_token_secret = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));

/* save them and identify those tokens as request token here */

//  returns the token, i.e
echo  "oauth_token=".$request_token_key."&oauth_token_secret=".$request_token_secret."&oauth_callback_confirmed=true";

As you can see in the code above there is a call to set_to_oauth_flow() method, this is to tell the provider we want to use OAuth and not xAuth. This mode is the default one. What it does in the background is unsetting the following required parameters:

\Zeflasher\OAuth\OAuthConstants::X_AUTH_USERNAME
\Zeflasher\OAuth\OAuthConstants::X_AUTH_PASSWORD
\Zeflasher\OAuth\OAuthConstants::X_AUTH_MODE

and set the following ones

\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_CONSUMER_KEY
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_TOKEN
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_SIGNATURE_METHOD
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_SIGNATURE
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_TIMESTAMP
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_NONCE

(Note that \Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_VERIFIER is not set by the library, you will have to set it manually (as it is optional))

This is why we call the set_request_token() afterwards as, as we have seen above, it removes some of the requested parameters for a normal OAuth request.

Setting up for an access token

Pretty much nothing to do but to check the request, generates the token and update your data

//  we are using the oauth flow
$this->set_to_oauth_flow();
//  check the request
$this->check_oauth_request();
$access_token = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));
$access_token_secret = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));

/* Here do something to remove the request token and store the access token (identified as so) */

//  returns the token, i.e
echo  "oauth_token=".$access_token_key."&oauth_token_secret=".$access_token_secret;

Setting up for an xAuth access token

The first thing to do here will be to tell the provider you are expecting a xAuth request. To do so call set_to_xauth_flow() method. This unset the following required parameters:

\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_TOKEN
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_VERIFIER
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_CALLBACK

and set the following ones

\Zeflasher\OAuth\OAuthConstants::X_AUTH_USERNAME
\Zeflasher\OAuth\OAuthConstants::X_AUTH_PASSWORD
\Zeflasher\OAuth\OAuthConstants::X_AUTH_MODE
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_CONSUMER_KEY
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_SIGNATURE_METHOD
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_SIGNATURE
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_TIMESTAMP
\Zeflasher\OAuth\OAuthConstants::OAUTH_CLIENT_NONCE

this also bypass the token check when verifying the request.

Here is an example

//  if we are requesting the xAuth mode
if( isset($params[\Zeflasher\OAuth\OAuthConstants::X_AUTH_MODE]) 
    && $params[\Zeflasher\OAuth\OAuthConstants::X_AUTH_MODE] == \Zeflasher\OAuth\OAuthConstants::X_AUTH_MODE_VALUE)
{
    //  we are using the xauth flow
    $this->set_to_xauth_flow();
    try
    {
        $this->check_oauth_request();
        //  load the user with given credentials, i.e x_auth_username and x_auth_password
        $user = new User();
        $user->username = $params[\Zeflasher\OAuth\OAuthConstants::X_AUTH_USERNAME];
        $user->password = $params[\Zeflasher\OAuth\OAuthConstants::X_AUTH_PASSWORD];
        if( $user->find() )
        {
            //  all good
            $access_token = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));
            $access_token_secret = sha1(\Zeflasher\OAuth\Provider\OAuthProvider::generate_token(20,true));

             /* Here do something to store the access token (identified as so) */   

             //  returns the token, i.e
             echo  "oauth_token=".$access_token_key."&oauth_token_secret=".$access_token_secret;
        
        }
        else
        {
            // user not found, do something
        }
    }
}