Everything documented, including clearer author attribution.

Renamed a few classes to rely more on OAuth namespace, instead of OAuth class prefix.

src/GaryJones/OAuth/Client.php

@@ -1,30 +1,35 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
-class Client
+/**
+ * Client holds the properties of a single client / consumer.
+ *
+ * @package OAuth
+ * @author Gary Jones <gary@garyjones.co.uk>
+ */
+class Client extends Credential
 {
-    protected $key;
+    /**
-    protected $secret;
+     * Constructs a new client object and populates the required parameters.
-
+     *
+     * @param string $key          Client key / identifier.
+     * @param string $secret       Client shared-secret.
+     * @param string $callback_url URL to which authorized request will redirect to.
+     */
     public function __construct($key, $secret, $callback_url = null)
     {
-        $this->key = $key;
+        $this->setKey($key);
-        $this->secret = $secret;
+        $this->setSecret($secret);
         $this->callback_url = $callback_url;
     }
-
-    public function getKey()
-    {
-        return $this->key;
-    }
-
-    public function getSecret()
-    {
-        return $this->secret;
-    }
-
-    public function __toString()
-    {
-        return "OAuthClient[key=$this->key,secret=$this->secret]";
-    }
 }

src/GaryJones/OAuth/Credential.php

@@ -0,0 +1,75 @@
+<?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
+namespace GaryJones\OAuth;
+
+/**
+ * Credential is the blueprint for all key + secret classes.
+ *
+ * @package OAuth
+ * @author Gary Jones <gary@garyjones.co.uk>
+ */
+abstract class Credential
+{
+    /**
+     * The credential key.
+     *
+     * @var string
+     */
+    protected $key;
+
+    /**
+     * The secret or shared-secret.
+     *
+     * @var string
+     */
+    protected $secret;
+
+    /**
+     * Return the credential key.
+     *
+     * @return string Credential key.
+     */
+    public function getKey()
+    {
+        return $this->key;
+    }
+
+    /**
+     * Set the credential key.
+     *
+     * @param string $key Credential identifier
+     */
+    public function setKey($key)
+    {
+        $this->key = $key;
+    }
+
+    /**
+     * Return the credential secret
+     *
+     * @return string
+     */
+    public function getSecret()
+    {
+        return $this->secret;
+    }
+
+    /**
+     * Set the credential key.
+     *
+     * @param string $key Credential identifier
+     */
+    public function setSecret($secret)
+    {
+        $this->secret = $secret;
+    }
+}

src/GaryJones/OAuth/DataStore.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
+namespace GaryJones\OAuth;
+
+/**
+ * The actual implementation of validating and assigning tokens is left up to
+ * the system using this library.
+ *
+ * @package OAuth
+ * @author Gary Jones <gary@garyjones.co.uk>
+ */
+interface DataStore
+{
+    /**
+     * Validate the client.
+     *
+     * @param string $client_key
+     */
+    public function lookupClient($client_key);
+
+    /**
+     * Validate a token.
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     * @param string                 $token_type Request or access token
+     */
+    public function lookupToken(Client $client, Token $token, $token_type);
+
+    /**
+     * Validate that a nonce has not been used with the same timestamp before.
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     * @param string                 $nonce
+     * @param int                    $timestamp
+     */
+    public function lookupNonce(Client $client, Token $token, $nonce, $timestamp);
+
+    /**
+     * Return a new token attached to this client.
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param string                 $callback URI to store as the post-authorization callback.
+     */
+    public function newRequestToken(Client $client, $callback = null);
+
+    /**
+     * Return a new access token attached to this consumer for the user
+     * associated with this token if the request token is authorized.
+     *
+     * Should also invalidate the request token.
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     * @param string                 $verifier
+     */
+    public function newAccessToken(Client $client, Token $token, $verifier = null);
+}

src/GaryJones/OAuth/Exception.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
+namespace GaryJones\OAuth;
+
+/**
+ * Generic exception class.
+ *
+ * @package OAuth
+ * @author Andy Smith
+ */
+class Exception extends \Exception
+{
+}

src/GaryJones/OAuth/HmacSha1.php

@@ -1,21 +1,58 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
 /**
- * The HMAC-SHA1 signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104]
+ * The HMAC-SHA1 signature method.
+ *
+ * The HMAC-SHA1 signature method. uses the HMAC-SHA1 signature algorithm as defined in [RFC2104]
  * where the Signature Base String is the text and the key is the concatenated values (each first
  * encoded per Parameter Encoding) of the Consumer Secret and Token Secret, separated by an '&'
  * character (ASCII code 38) even if empty.
  *   - Chapter 9.2 ("HMAC-SHA1")
+ *
+ * @package OAuth
+ * @author Andy Smith
  */
 class HmacSha1 extends SignatureMethod
 {
+    /**
+     * Return the name of the Signature Method.
+     *
+     * @return string
+     */
     public function getName()
     {
         return 'HMAC-SHA1';
     }
 
-    public function buildSignature($request, $client, $token)
+    /**
+     * Build up the signature.
+     *
+     * oauth_signature is set to the concatenated encoded values of the Client Secret and
+     * Token Secret, separated by a '&' character (ASCII code 38), even if either secret is
+     * empty. The result MUST be encoded again.
+     *   - Chapter 9.4.1 ("Generating Signatures")
+     *
+     * Please note that the second encoding MUST NOT happen in the SignatureMethod, as
+     * OAuthRequest handles this!
+     *
+     * @param GaryJones\OAuth\Request $request
+     * @param GaryJones\OAuth\Client  $client
+     * @param GaryJones\OAuth\Token   $token
+     *
+     * @return string
+     */
+    public function buildSignature(Request $request, Client $client, Token $token)
     {
         $base_string = $request->getSignatureBaseString();
         $request->base_string = $base_string;

src/GaryJones/OAuth/OAuthDataStore.php

@@ -1,49 +0,0 @@
-<?php
-namespace GaryJones\OAuth;
-
-interface OAuthDataStore
-{
-    /**
-     * Lookup the client.
-     *
-     * @param string $client_key
-     */
-    public function lookupClient($client_key);
-
-    /**
-     *
-     * @param type $client
-     * @param type $token_type
-     * @param type $token
-     */
-    public function lookupToken($client, $token_type, $token);
-
-    /**
-     *
-     * @param type $client
-     * @param type $token
-     * @param type $nonce
-     * @param type $timestamp
-     */
-    public function lookupNonce($client, $token, $nonce, $timestamp);
-
-    /**
-     * Return a new token attached to this consumer.
-     *
-     * @param type $client
-     * @param type $callback
-     */
-    public function newRequestToken($client, $callback = null);
-
-    /**
-     * Return a new access token attached to this consumer for the user
-     * associated with this token if the request token is authorized.
-     *
-     * Should also invalidate the request token.
-     *
-     * @param type $token
-     * @param type $client
-     * @param type $verifier
-     */
-    public function newAccessToken($token, $client, $verifier = null);
-}

src/GaryJones/OAuth/OAuthException.php

@@ -1,10 +0,0 @@
-<?php
-namespace GaryJones\OAuth;
-
-/**
- * Generic exception class.
- */
-class OAuthException extends \Exception
-{
-    // pass
-}

src/GaryJones/OAuth/OAuthServer.php

@@ -1,207 +0,0 @@
-<?php
-namespace GaryJones\OAuth;
-
-class OAuthServer
-{
-    protected $timestamp_threshold = 300; // in seconds, five minutes
-    protected $version = '1.0';
-    protected $signature_methods = array();
-    protected $data_store;
-
-    public function __construct(OAuthDataStore $data_store)
-    {
-        $this->data_store = $data_store;
-    }
-
-    public function addSignatureMethod($signature_method)
-    {
-        $this->signature_methods[$signature_method->getName()] =
-            $signature_method;
-    }
-
-    // high level functions
-
-    /**
-     * process a request_token request
-     * returns the request token on success
-     */
-    public function fetchRequestToken(&$request)
-    {
-        $this->getVersion($request);
-
-        $client = $this->getClient($request);
-
-        // no token required for the initial token request
-        $token = null;
-
-        $this->checkSignature($request, $client, $token);
-
-        // Rev A change
-        $callback = $request->getParameter('oauth_callback');
-        $new_token = $this->data_store->newRequestToken($client, $callback);
-
-        return $new_token;
-    }
-
-    /**
-     * process an access_token request
-     * returns the access token on success
-     */
-    public function fetchAccessToken(&$request)
-    {
-        $this->getVersion($request);
-
-        $client = $this->getClient($request);
-
-        // requires authorized request token
-        $token = $this->getToken($request, $client, 'request');
-
-        $this->checkSignature($request, $client, $token);
-
-        // Rev A change
-        $verifier = $request->getParameter('oauth_verifier');
-        $new_token = $this->data_store->newAccessToken($token, $client, $verifier);
-
-        return $new_token;
-    }
-
-    /**
-     * verify an api call, checks all the parameters
-     */
-    public function verifyRequest(&$request)
-    {
-        $this->getVersion($request);
-        $client = $this->getClient($request);
-        $token = $this->getToken($request, $client, 'access');
-        $this->checkSignature($request, $client, $token);
-        return array($client, $token);
-    }
-
-    // Internals from here
-    /**
-     * version 1
-     */
-    private function getVersion(&$request)
-    {
-        $version = $request->getParameter('oauth_version');
-        if (!$version) {
-            // Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present.
-            // Chapter 7.0 ("Accessing Protected Ressources")
-            $version = '1.0';
-        }
-        if ($version !== $this->version) {
-            throw new OAuthException("OAuth version '$version' not supported");
-        }
-        return $version;
-    }
-
-    /**
-     * figure out the signature with some defaults
-     */
-    private function getSignatureMethod($request)
-    {
-        $signature_method = $request instanceof OAuthRequest ? $request->getParameter('oauth_signature_method') : null;
-
-        if (!$signature_method) {
-            // According to chapter 7 ("Accessing Protected Ressources") the signature-method
-            // parameter is required, and we can't just fallback to PLAINTEXT
-            throw new OAuthException('No signature method parameter. This parameter is required');
-        }
-
-        if (!in_array($signature_method, array_keys($this->signature_methods))) {
-            throw new OAuthException(
-                "Signature method '$signature_method' not supported, try one of the following: " .
-                implode(", ", array_keys($this->signature_methods))
-            );
-        }
-        return $this->signature_methods[$signature_method];
-    }
-
-    /**
-     * try to find the client for the provided request's client key
-     */
-    private function getClient($request)
-    {
-        $client_key = $request instanceof OAuthRequest ? $request->getParameter('oauth_consumer_key') : null;
-
-        if (!$client_key) {
-            throw new OAuthException('Invalid client key');
-        }
-
-        $client = $this->data_store->lookupClient($client_key);
-        if (!$client) {
-            throw new OAuthException('Invalid client');
-        }
-
-        return $client;
-    }
-
-    /**
-     * try to find the token for the provided request's token key
-     */
-    private function getToken($request, $client, $token_type = 'access')
-    {
-        $token_field = $request instanceof OAuthRequest ? $request->getParameter('oauth_token') : null;
-
-        $token = $this->data_store->lookupToken($client, $token_type, $token_field);
-        if (!$token) {
-            throw new OAuthException("Invalid $token_type token: $token_field");
-        }
-        return $token;
-    }
-
-    /**
-     * all-in-one function to check the signature on a request
-     * should guess the signature method appropriately
-     */
-    private function checkSignature($request, $client, $token)
-    {
-        // this should probably be in a different method
-        $timestamp = $request instanceof OAuthRequest ? $request->getParameter('oauth_timestamp') : null;
-        $nonce = $request instanceof OAuthRequest ? $request->getParameter('oauth_nonce') : null;
-
-        $this->checkTimestamp($timestamp);
-        $this->checkNonce($client, $token, $nonce, $timestamp);
-
-        $signature_method = $this->getSignatureMethod($request);
-
-        $signature = $request->getParameter('oauth_signature');
-        $valid_sig = $signature_method->checkSignature($request, $client, $token, $signature);
-
-        if (!$valid_sig) {
-            throw new OAuthException('Invalid signature');
-        }
-    }
-
-    /**
-     * check that the timestamp is new enough
-     */
-    private function checkTimestamp($timestamp)
-    {
-        if (!$timestamp) {
-            throw new OAuthException('Missing timestamp parameter. The parameter is required');
-        }
-
-        // verify that timestamp is recentish
-        $now = time();
-        if (abs($now - $timestamp) > $this->timestamp_threshold) {
-            throw new OAuthException("Expired timestamp, yours $timestamp, ours $now");
-        }
-    }
-
-    /**
-     * check that the nonce is not repeated
-     */
-    private function checkNonce($client, $token, $nonce, $timestamp)
-    {
-        if (!$nonce) {
-            throw new OAuthException('Missing nonce parameter. The parameter is required');
-        }
-
-        // verify that the nonce is uniqueish
-        $found = $this->data_store->lookupNonce($client, $token, $nonce, $timestamp);
-        if ($found) {
-            throw new OAuthException('Nonce already used: ' . $nonce);
-        }
-    }
-}

src/GaryJones/OAuth/PlainText.php

@@ -1,19 +1,41 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
 /**
+ * PLAINTEXT signature method.
+ *
  * The PLAINTEXT method does not provide any security protection and SHOULD only be used
  * over a secure channel such as HTTPS. It does not use the Signature Base String.
  *   - Chapter 9.4 ("PLAINTEXT")
+ *
+ * @package OAuth
+ * @author Andy Smith
  */
 class PlainText extends SignatureMethod
 {
+    /**
+     * Return the name of the Signature Method.
+     *
+     * @return string
+     */
     public function getName()
     {
         return 'PLAINTEXT';
     }
 
     /**
+     * Build up the signature.
+     *
      * oauth_signature is set to the concatenated encoded values of the Client Secret and
      * Token Secret, separated by a '&' character (ASCII code 38), even if either secret is
      * empty. The result MUST be encoded again.
@@ -21,8 +43,14 @@ class PlainText extends SignatureMethod
      *
      * Please note that the second encoding MUST NOT happen in the SignatureMethod, as
      * OAuthRequest handles this!
+     *
+     * @param GaryJones\OAuth\Request $request
+     * @param GaryJones\OAuth\Client  $client
+     * @param GaryJones\OAuth\Token   $token
+     *
+     * @return string
      */
-    public function buildSignature($request, $client, $token)
+    public function buildSignature(Request $request, Client $client, Token $token)
     {
         $key_parts = array(
             $client->getSecret(),

src/GaryJones/OAuth/Request.php

@@ -1,17 +1,67 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
-class OAuthRequest
+/**
+ * Handle an OAuth request.
+ *
+ * @package OAuth
+ * @author Andy Smith
+ */
+class Request
 {
+    /**
+     * HTTP parameters.
+     *
+     * @var array
+     */
     protected $parameters;
+
+    /**
+     * HTTP method - likely GET or POST.
+     *
+     * @var string HTTP method.
+     */
     protected $http_method;
+
+    /**
+     * The URL the request was made to.
+     *
+     * @var string Request URL.
+     */
     protected $http_url;
-    // for debug purposes
+
-    public $base_string;
+    /**
+     * OAuth version.
+     *
+     * @var string
+     */
     public static $version = '1.0';
+
+    /**
+     * Stream of POSTed file.
+     *
+     * @var string
+     */
     public static $POST_INPUT = 'php://input';
 
-    public function __construct($http_method, $http_url, $parameters = null)
+    /**
+     * Construct a Request object.
+     *
+     * @param string $http_method Request HTTP method.
+     * @param string $http_url    Request URL.
+     * @param array  $parameters  HTTP parameters.
+     */
+    public function __construct($http_method, $http_url, array $parameters = null)
     {
         $parameters = ($parameters) ? $parameters : array();
         $this->parameters = array_merge(Util::parseParameters(parse_url($http_url, PHP_URL_QUERY)), $parameters);
@@ -20,11 +70,20 @@ class OAuthRequest
     }
 
     /**
-     * attempt to build up a request from what was passed to the server
+     * a
+     */
+    /**
+     * Attempt to build up a request from what was passed to the server.
+     *
+     * @param string $http_method Request HTTP method.
+     * @param string $http_url    Request URL.
+     * @param array  $parameters  HTTP parameters.
+     *
+     * @return GaryJones\OAuth\Request
      */
     public static function fromRequest($http_method = null, $http_url = null, $parameters = null)
     {
-        $scheme = (!isset($_SERVER['HTTPS']) || $_SERVER['HTTPS'] != "on") ? 'http' : 'https';
+        $scheme = (!isset($_SERVER['HTTPS']) || $_SERVER['HTTPS'] != 'on') ? 'http' : 'https';
         $http_url = ($http_url) ? $http_url : $scheme .
             '://' . $_SERVER['HTTP_HOST'] .
             ':' .
@@ -45,7 +104,7 @@ class OAuthRequest
 
             // It's a POST request of the proper content-type, so parse POST
             // parameters and add those overriding any duplicates from GET
-            if ($http_method == "POST"
+            if ('POST' == $http_method
                 && isset($request_headers['Content-Type'])
                 && strstr($request_headers['Content-Type'], 'application/x-www-form-urlencoded')
             ) {
@@ -66,28 +125,49 @@ class OAuthRequest
             }
         }
 
-        return new OAuthRequest($http_method, $http_url, $parameters);
+        return new Request($http_method, $http_url, $parameters);
     }
 
     /**
-     * pretty much a helper function to set up the request
+     * Helper function to set up the request.
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     * @param string                 $http_method
+     * @param string                 $http_url
+     * @param array                  $parameters
+     *
+     * @return GaryJones\OAuth\Request
      */
-    public static function fromClientAndToken($client, $token, $http_method, $http_url, $parameters = null)
+    public static function fromClientAndToken(
-    {
+        Client $client,
+        Token $token,
+        $http_method,
+        $http_url,
+        array $parameters = null
+    ) {
         $parameters = ($parameters) ? $parameters : array();
-        $defaults = array("oauth_version" => OAuthRequest::$version,
+        $defaults = array(
-            "oauth_nonce" => OAuthRequest::generateNonce(),
+            'oauth_version' => Request::$version,
-            "oauth_timestamp" => OAuthRequest::generateTimestamp(),
+            'oauth_nonce' => Request::generateNonce(),
-            "oauth_consumer_key" => $client->getKey());
+            'oauth_timestamp' => Request::generateTimestamp(),
+            'oauth_consumer_key' => $client->getKey());
         if ($token) {
             $defaults['oauth_token'] = $token->getKey();
         }
 
         $parameters = array_merge($defaults, $parameters);
 
-        return new OAuthRequest($http_method, $http_url, $parameters);
+        return new Request($http_method, $http_url, $parameters);
     }
 
+    /**
+     * Add additional parameter to Request.
+     *
+     * @param string $name
+     * @param string $value
+     * @param bool   $allow_duplicates
+     */
     public function setParameter($name, $value, $allow_duplicates = true)
     {
         if ($allow_duplicates && isset($this->parameters[$name])) {
@@ -104,16 +184,33 @@ class OAuthRequest
         }
     }
 
+    /**
+     * Get single request parameter by name.
+     *
+     * @param string $name
+     *
+     * @return string
+     */
     public function getParameter($name)
     {
         return isset($this->parameters[$name]) ? $this->parameters[$name] : null;
     }
 
+    /**
+     * Get all request parameters.
+     *
+     * @return array
+     */
     public function getParameters()
     {
         return $this->parameters;
     }
 
+    /**
+     * Unset single request parameter by name.
+     *
+     * @param string $name
+     */
     public function unsetParameter($name)
     {
         unset($this->parameters[$name]);
@@ -121,12 +218,13 @@ class OAuthRequest
 
     /**
      * The request parameters, sorted and concatenated into a normalized string.
+     *
      * @return string
      */
     public function getSignableParameters()
     {
         // Grab all parameters
-        $params = $this->parameters;
+        $params = $this->getParameters();
 
         // Remove oauth_signature if present
         // Ref: Spec: 9.1.1 ("The oauth_signature parameter MUST be excluded.")
@@ -158,7 +256,9 @@ class OAuthRequest
     }
 
     /**
-     * Just uppercases the http method
+     * Uppercases the HTTP method.
+     *
+     * @return string
      */
     public function getNormalizedHttpMethod()
     {
@@ -166,8 +266,10 @@ class OAuthRequest
     }
 
     /**
-     * parses the url and rebuilds it to be
+     * Parses the url and rebuilds it to be
      * scheme://host/path
+     *
+     * @return string URL
      */
     public function getNormalizedHttpUrl()
     {
@@ -194,7 +296,9 @@ class OAuthRequest
     }
 
     /**
-     * builds a url usable for a GET request
+     * Builds a URL usable for a GET request.
+     *
+     * @return string
      */
     public function toUrl()
     {
@@ -207,15 +311,23 @@ class OAuthRequest
     }
 
     /**
-     * builds the data one would send in a POST request
+     * Builds the data one would send in a POST request.
+     *
+     * @return string
      */
     public function toPostdata()
     {
-        return Util::buildHttpQuery($this->parameters);
+        return Util::buildHttpQuery($this->getParameters());
     }
 
     /**
-     * builds the Authorization: header
+     * Builds the Authorization: header.
+     *
+     * @param string $realm Authorization realm.
+     *
+     * @return string
+     *
+     * @throws GaryJones\OAuth\Exception
      */
     public function toHeader($realm = null)
     {
@@ -233,7 +345,7 @@ class OAuthRequest
                 continue;
             }
             if (is_array($v)) {
-                throw new OAuthException('Arrays not supported in headers');
+                throw new Exception('Arrays not supported in headers');
             }
             $out .= ($first) ? ' ' : ',';
             $out .= Util::urlencodeRfc3986($k) .
@@ -245,26 +357,48 @@ class OAuthRequest
         return $out;
     }
 
+    /**
+     * Return request object cast as string.
+     *
+     * @return string
+     */
     public function __toString()
     {
         return $this->toUrl();
     }
 
-    public function signRequest($signature_method, $client, $token)
+    /**
+     * Build signature and add it as parameter.
+     *
+     * @param string                 $signature_method
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     */
+    public function signRequest($signature_method, Client $client, Token $token)
     {
         $this->setParameter('oauth_signature_method', $signature_method->getName(), false);
         $signature = $this->buildSignature($signature_method, $client, $token);
         $this->setParameter('oauth_signature', $signature, false);
     }
 
-    public function buildSignature($signature_method, $client, $token)
+    /**
+     * Build signature.
+     *
+     * @param string                 $signature_method
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     *
+     * @return string
+     */
+    public function buildSignature($signature_method, Client $client, Token $token)
     {
-        $signature = $signature_method->buildSignature($this, $client, $token);
+        return $signature_method->buildSignature($this, $client, $token);
-        return $signature;
     }
 
     /**
-     * util function: current timestamp
+     * Get current time.
+     *
+     * @return int Timestamp.
      */
     private static function generateTimestamp()
     {
@@ -272,13 +406,12 @@ class OAuthRequest
     }
 
     /**
-     * util function: current nonce
+     * Generate nonce.
+     *
+     * @return string 32-character hexadecimal number.
      */
     private static function generateNonce()
     {
-        $mt = microtime();
+        return md5(microtime() . mt_rand()); // md5s look nicer than numbers
-        $rand = mt_rand();
-
-        return md5($mt . $rand); // md5s look nicer than numbers
     }
 }

src/GaryJones/OAuth/RsaSha1.php

@@ -1,39 +1,73 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
 /**
+ * The RSA-SHA1 signature method.
+ *
  * The RSA-SHA1 signature method uses the RSASSA-PKCS1-v1_5 signature algorithm as defined in
  * [RFC3447] section 8.2 (more simply known as PKCS#1), using SHA-1 as the hash function for
  * EMSA-PKCS1-v1_5. It is assumed that the Client has provided its RSA public key in a
  * verified way to the Service Provider, in a manner which is beyond the scope of this
  * specification.
  *   - Chapter 9.3 ("RSA-SHA1")
+ *
+ * @package OAuth
+ * @author Andy Smith
  */
 abstract class RsaSha1 extends SignatureMethod
 {
+    /**
+     * Return the name of the Signature Method.
+     *
+     * @return string
+     */
     public function getName()
     {
         return "RSA-SHA1";
     }
 
-    // Up to the SP to implement this lookup of keys. Possible ideas are:
+    /**
-    // (1) do a lookup in a table of trusted certs keyed off of client
+     * Up to the SP to implement this lookup of keys. Possible ideas are:
-    // (2) fetch via http using a url provided by the requester
+     * (1) do a lookup in a table of trusted certs keyed off of client
-    // (3) some sort of specific discovery code based on request
+     * (2) fetch via http using a url provided by the requester
-    //
+     * (3) some sort of specific discovery code based on request
-    // Either way should return a string representation of the certificate
+     *
+     * Either way should return a string representation of the certificate
+     *
+     */
     abstract protected function fetchPublicCert(&$request);
 
-    // Up to the SP to implement this lookup of keys. Possible ideas are:
+    /**
-    // (1) do a lookup in a table of trusted certs keyed off of client
+     * Up to the SP to implement this lookup of keys. Possible ideas are:
-    //
+     * (1) do a lookup in a table of trusted certs keyed off of client
-    // Either way should return a string representation of the certificate
+     *
+     * Either way should return a string representation of the certificate
+     */
     abstract protected function fetchPrivateCert(&$request);
 
-    public function buildSignature($request, $client, $token)
+    /**
+     * Build up the signature.
+     *
+     * @param GaryJones\OAuth\Request $request
+     * @param GaryJones\OAuth\Client  $client
+     * @param GaryJones\OAuth\Token   $token
+     *
+     * @return string
+     */
+    public function buildSignature(Request $request, Client $client, Token $token)
     {
         $base_string = $request->getSignatureBaseString();
-        $request->base_string = $base_string;
+        //$request->base_string = $base_string;
 
         // Fetch the private key cert based on the request
         $cert = $this->fetchPrivateCert($request);
@@ -50,12 +84,22 @@ abstract class RsaSha1 extends SignatureMethod
         return base64_encode($signature);
     }
 
-    public function checkSignature($request, $client, $token, $signature)
+    /**
+     * Verifies that a given signature is correct.
+     *
+     * @param GaryJones\OAuth\Request  $request
+     * @param GaryJones\OAuth\Consumer $client
+     * @param GaryJones\OAuth\Token    $token
+     * @param string                   $signature
+     *
+     * @return bool
+     */
+    public function checkSignature(Request $request, Client $client, Token $token, $signature)
     {
-        $decoded_sig = base64_decode($signature);
-
         $base_string = $request->getSignatureBaseString();
 
+        $decoded_sig = base64_decode($signature);
+
         // Fetch the public key cert based on the request
         $cert = $this->fetchPublicCert($request);
 

src/GaryJones/OAuth/Server.php

@@ -0,0 +1,315 @@
+<?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
+namespace GaryJones\OAuth;
+
+/**
+ * OAuth server.
+ *
+ * @package OAuth
+ * @author Andy Smith
+ */
+class Server
+{
+    /**
+     * Limit to which timestamp is accepted, in seconds.
+     *
+     * Requests older than now - this value, are rejected as possible replay attack.
+     *
+     * @var int
+     */
+    protected $timestamp_threshold = 300; // 5 minutes
+
+    /**
+     * OAuth version.
+     *
+     * @var string
+     */
+    protected $version = '1.0';
+
+    /**
+     * Supported signature methods.
+     *
+     * @var array
+     */
+    protected $signature_methods = array();
+
+    /**
+     * Data store object reference.
+     *
+     * @var GaryJones\OAuth\DataStore
+     */
+    protected $data_store;
+
+    /**
+     * Construct OAuth server instance.
+     *
+     * @param GaryJones\OAuth\DataStore $data_store
+     */
+    public function __construct(DataStore $data_store)
+    {
+        $this->data_store = $data_store;
+    }
+
+    /**
+     * Add a supported signature method.
+     *
+     * @param GaryJones\OAuth\SignatureMethod $signature_method
+     */
+    public function addSignatureMethod(SignatureMethod $signature_method)
+    {
+        $this->signature_methods[$signature_method->getName()] =
+            $signature_method;
+    }
+
+    // high level functions
+
+    /**
+     * Process a temporary credential (request_token) request.
+     *
+     * Returns the request token on success
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return GaryJones\OAuth\Token
+     */
+    public function fetchRequestToken(Request &$request)
+    {
+        $this->getVersion($request);
+
+        $client = $this->getClient($request);
+
+        // no token required for the initial token request
+        $token = null;
+
+        $this->checkSignature($request, $client, $token);
+
+        // Rev A change
+        $callback = $request->getParameter('oauth_callback');
+
+        return $this->data_store->newRequestToken($client, $callback);
+    }
+
+    /**
+     * Process a post-authorization token (access_token) request.
+     *
+     * Returns the access token on success.
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return GaryJones\OAuth\Token
+     */
+    public function fetchAccessToken(Request &$request)
+    {
+        $this->getVersion($request);
+
+        $client = $this->getClient($request);
+
+        // requires authorized request token
+        $token = $this->getToken($request, $client, 'request');
+
+        $this->checkSignature($request, $client, $token);
+
+        // Rev A change
+        $verifier = $request->getParameter('oauth_verifier');
+
+        return $this->data_store->newAccessToken($token, $client, $verifier);
+    }
+
+    /**
+     * Verify an api call, checks all the parameters.
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return array Client and Token
+     */
+    public function verifyRequest(Request &$request)
+    {
+        $this->getVersion($request);
+        $client = $this->getClient($request);
+        $token = $this->getToken($request, $client, 'access');
+        $this->checkSignature($request, $client, $token);
+        return array($client, $token);
+    }
+
+    // Internals from here
+
+    /**
+     * Check that version is 1.0.
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return string
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function getVersion(Request &$request)
+    {
+        $version = $request->getParameter('oauth_version');
+        if (!$version) {
+            // Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present.
+            // Chapter 7.0 ("Accessing Protected Ressources")
+            $version = '1.0';
+        }
+        if ($version !== $this->version) {
+            throw new Exception("OAuth version '$version' not supported");
+        }
+        return $version;
+    }
+
+    /**
+     * Get the signature method name, and if it is supported.
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return string Signature method name.
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function getSignatureMethod(Request $request)
+    {
+        $signature_method = $request instanceof Request ? $request->getParameter('oauth_signature_method') : null;
+
+        if (!$signature_method) {
+            // According to chapter 7 ("Accessing Protected Resources") the signature-method
+            // parameter is required, and we can't just fallback to PLAINTEXT
+            throw new Exception('No signature method parameter. This parameter is required');
+        }
+
+        if (!in_array($signature_method, array_keys($this->signature_methods))) {
+            throw new Exception(
+                "Signature method '$signature_method' not supported, try one of the following: " .
+                implode(", ", array_keys($this->signature_methods))
+            );
+        }
+        return $this->signature_methods[$signature_method];
+    }
+
+    /**
+     * Try to find the client for the provided request's client key.
+     *
+     * @param GaryJones\OAuth\Request $request
+     *
+     * @return GaryJones\OAuth\Client
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function getClient(Request $request)
+    {
+        $client_key = $request instanceof Request ? $request->getParameter('oauth_consumer_key') : null;
+
+        if (!$client_key) {
+            throw new Exception('Invalid client key');
+        }
+
+        $client = $this->data_store->lookupClient($client_key);
+        if (!$client) {
+            throw new Exception('Invalid client');
+        }
+
+        return $client;
+    }
+
+    /**
+     * Try to find the token for the provided request's token key.
+     *
+     * @param GaryJones\OAuth\Request $request
+     * @param GaryJones\OAuth\Client  $client
+     * @param string                   $token_type
+     *
+     * @return GaryJones\OAuth\Token
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function getToken(Request $request, Client $client, $token_type = 'access')
+    {
+        $token_field = $request instanceof Request ? $request->getParameter('oauth_token') : null;
+
+        $token = $this->data_store->lookupToken($client, $token_type, $token_field);
+        if (!$token) {
+            throw new Exception("Invalid $token_type token: $token_field");
+        }
+        return $token;
+    }
+
+    /**
+     * All-in-one function to check the signature on a request.
+     *
+     * Should determine the signature method appropriately
+     *
+     * @param GaryJones\OAuth\Request $request
+     * @param GaryJones\OAuth\Client  $client
+     * @param GaryJones\OAuth\Token   $token
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function checkSignature(Request $request, Client $client, Token $token)
+    {
+        // this should probably be in a different method
+        $timestamp = $request instanceof Request ? $request->getParameter('oauth_timestamp') : null;
+        $nonce = $request instanceof Request ? $request->getParameter('oauth_nonce') : null;
+
+        $this->checkTimestamp($timestamp);
+        $this->checkNonce($client, $token, $nonce, $timestamp);
+
+        $signature_method = $this->getSignatureMethod($request);
+
+        $signature = $request->getParameter('oauth_signature');
+        $valid_sig = $signature_method->checkSignature($request, $client, $token, $signature);
+
+        if (!$valid_sig) {
+            throw new Exception('Invalid signature');
+        }
+    }
+
+    /**
+     * Check that the timestamp is new enough
+     *
+     * @param int $timestamp
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function checkTimestamp($timestamp)
+    {
+        if (!$timestamp) {
+            throw new Exception('Missing timestamp parameter. The parameter is required');
+        }
+
+        // verify that timestamp is recentish
+        $now = time();
+        if (abs($now - $timestamp) > $this->timestamp_threshold) {
+            throw new Exception("Expired timestamp, yours $timestamp, ours $now");
+        }
+    }
+
+    /**
+     * Check that the nonce is not repeated
+     *
+     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Token  $token
+     * @param string                 $nonce
+     * @param int                    $timestamp
+     *
+     * @throws GaryJones\OAuth\Exception
+     */
+    private function checkNonce(Client $client, Token $token, $nonce, $timestamp)
+    {
+        if (!$nonce) {
+            throw new Exception('Missing nonce parameter. The parameter is required');
+        }
+
+        // verify that the nonce is uniqueish
+        $found = $this->data_store->lookupNonce($client, $token, $nonce, $timestamp);
+        if ($found) {
+            throw new Exception('Nonce already used: ' . $nonce);
+        }
+    }
+}

src/GaryJones/OAuth/SignatureMethod.php

@@ -1,14 +1,30 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
 /**
- * A class for implementing a Signature Method
+ * A class for implementing a Signature Method.
+ *
  * See section 9 ("Signing Requests") in the spec
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
  */
 abstract class SignatureMethod
 {
     /**
-     * Needs to return the name of the Signature Method (ie HMAC-SHA1)
+     * Return the name of the Signature Method (ie HMAC-SHA1).
+     *
      * @return string
      */
     abstract public function getName();
@@ -20,23 +36,25 @@ abstract class SignatureMethod
      * the encoding is handled in OAuthRequest when the final
      * request is serialized.
      *
-     * @param GaryJones\OAuth\OAuthRequest $request
+     * @param GaryJones\OAuth\Request $request
-     * @param GaryJones\OAuth\Client $client
+     * @param GaryJones\OAuth\Client  $client
-     * @param GaryJones\OAuth\Token $token
+     * @param GaryJones\OAuth\Token   $token
+     *
      * @return string
      */
-    abstract public function buildSignature($request, $client, $token);
+    abstract public function buildSignature(Request $request, Client $client, Token $token);
 
     /**
      * Verifies that a given signature is correct.
      *
-     * @param GaryJones\OAuth\OAuthRequest $request
+     * @param GaryJones\OAuth\Request  $request
      * @param GaryJones\OAuth\Consumer $client
-     * @param GaryJones\OAuth\Token $token
+     * @param GaryJones\OAuth\Token    $token
-     * @param string $signature
+     * @param string                   $signature
+     *
      * @return bool
      */
-    public function checkSignature($request, $client, $token, $signature)
+    public function checkSignature(Request $request, Client $client, Token $token, $signature)
     {
         $built = $this->buildSignature($request, $client, $token);
         return $built == $signature;

src/GaryJones/OAuth/Token.php

@@ -1,44 +1,47 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
-class Token
+/**
+ * Token holds the properties of a single token.
+ *
+ * This class deals with both temporary (request) and token (access) credntials.
+ *
+ * @package OAuth
+ * @author Gary Jones <gary@garyjones.co.uk>
+ */
+class Token extends Credential
 {
-    // access tokens and request tokens
-    protected $key;
-    protected $secret;
-
     /**
-     * key = the token
+     * Constructs a new client object and populates the required parameters.
-     * secret = the token secret
+     *
+     * @param string $key    Client key / identifier.
+     * @param string $secret Client shared-secret.
      */
     public function __construct($key, $secret)
     {
-        $this->key = $key;
+        $this->setKey($key);
-        $this->secret = $secret;
+        $this->setSecret($secret);
-    }
-
-    public function getKey()
-    {
-        return $this->key;
-    }
-
-    public function getSecret()
-    {
-        return $this->secret;
     }
 
     /**
-     * generates the basic string serialization of a token that a server
+     * Generates the basic string serialization of a token that a server
-     * would respond to request_token and access_token calls with
+     * would respond to request_token and access_token calls with.
+     *
+     * @return string
      */
     public function toString()
     {
         return 'oauth_token=' . Util::urlencodeRfc3986($this->key) .
             '&oauth_token_secret=' . Util::urlencodeRfc3986($this->secret);
     }
-
-    public function __toString()
-    {
-        return $this->toString();
-    }
 }

src/GaryJones/OAuth/Util.php

@@ -1,8 +1,31 @@
 <?php
+/**
+ * OAuth
+ *
+ * @package OAuth
+ * @author Andy Smith
+ * @author Gary Jones <gary@garyjones.co.uk>
+ * @license https://raw.github.com/GaryJones/OAuth/master/LICENSE MIT
+ * @link https://github.com/GaryJones/OAuth
+ */
+
 namespace GaryJones\OAuth;
 
+/**
+ * Group of static utility methods.
+ *
+ * @package OAuth
+ * @author Andy Smith
+ */
 class Util
 {
+    /**
+     * Encode a string according to RFC 3986.
+     *
+     * @param string $input
+     *
+     * @return string Encoded string.
+     */
     public static function urlencodeRfc3986($input)
     {
         if (is_array($input)) {
@@ -14,19 +37,34 @@ class Util
         }
     }
 
-    // This decode function isn't taking into consideration the above
+    /**
-    // modifications to the encoding process. However, this method doesn't
+     * Decode a string.
-    // seem to be used anywhere so leaving it as is.
+     *
+     * This decode function isn't taking into consideration the above modifications to the encoding process.
+     * However, this method doesn't seem to be used anywhere so leaving it as is.
+     *
+     * @param string $string
+     *
+     * @return string Decoded string.
+     */
     public static function urldecodeRfc3986($string)
     {
         return urldecode($string);
     }
 
-    // Utility function for turning the Authorization: header into
+    /**
-    // parameters, has to do some unescaping
+     * Utility function for turning the Authorization: header into parameters.
-    // Can filter out any non-oauth parameters if needed (default behaviour)
+     *
-    // May 28th, 2010 - method updated to tjerk.meesters for a speed improvement.
+     * Has to do some unescaping. Can filter out any non-oauth parameters if needed (default behaviour).
-    //                  see http://code.google.com/p/oauth/issues/detail?id=163
+     *
+     * May 28th, 2010 - method updated to tjerk.meesters for a speed improvement.
+     *                  see http://code.google.com/p/oauth/issues/detail?id=163
+     *
+     * @param string $header
+     * @param bool   $only_allow_oauth_parameters
+     *
+     * @return array
+     */
     public static function splitHeader($header, $only_allow_oauth_parameters = true)
     {
         $params = array();
@@ -42,9 +80,14 @@ class Util
         return $params;
     }
 
-    // helper to try to sort out headers for people who aren't running apache
+    /**
+     * Helper to try to sort out headers for people who aren't running apache
+     *
+     * @return array
+     */
     public static function getHeaders()
     {
+        $out = array();
         if (function_exists('apache_request_headers')) {
             // we need this to get the actual Authorization: header
             // because apache tends to tell us it doesn't exist
@@ -54,7 +97,6 @@ class Util
             // we always want the keys to be Cased-Like-This and arh()
             // returns the headers in the same case as they are in the
             // request
-            $out = array();
             foreach ($headers as $key => $value) {
                 $key = str_replace(' ', '-', ucwords(strtolower(str_replace('-', ' ', $key))));
                 $out[$key] = $value;
@@ -62,7 +104,6 @@ class Util
         } else {
             // otherwise we don't have apache and are just going to have to hope
             // that $_SERVER actually contains what we need
-            $out = array();
             if (isset($_SERVER['CONTENT_TYPE'])) {
                 $out['Content-Type'] = $_SERVER['CONTENT_TYPE'];
             }
@@ -83,9 +124,17 @@ class Util
         return $out;
     }
 
-    // This function takes a input like a=b&a=c&d=e and returns the parsed
+    /**
-    // parameters like this
+     * Pull key=value querystring into an array.
-    // array('a' => array('b','c'), 'd' => 'e')
+     *
+     * This function takes a input like a=b&a=c&d=e and returns the parsed
+     * parameters like this
+     * array('a' => array('b','c'), 'd' => 'e')
+     *
+     * @param string $input
+     *
+     * @return array
+     */
     public static function parseParameters($input)
     {
         if (!isset($input) || !$input) {
@@ -118,7 +167,14 @@ class Util
         return $parsed_parameters;
     }
 
-    public static function buildHttpQuery($params)
+    /**
+     * Build query string from parameters, with correct encoding.
+     *
+     * @param array $params
+     *
+     * @return string
+     */
+    public static function buildHttpQuery(array $params)
     {
         if (!$params) {
             return '';