Updated docblocks for the two main classes

src/OAuth2/AuthServer.php

@@ -1,4 +1,13 @@
 <?php
+/**
+ * OAuth 2.0 Authentication Server
+ *
+ * @package     lncd/oauth2
+ * @author      Alex Bilbie <hello@alexbilbie.com>
+ * @copyright   Copyright (c) 2013 University of Lincoln
+ * @license     http://mit-license.org/
+ * @link        http://github.com/lncd/oauth2
+ */
 
 namespace OAuth2;
 
@@ -9,6 +18,9 @@ use OAuth2\Storage\ClientInterface;
 use OAuth2\Storage\ScopeInterface;
 use OAuth2\Grant\GrantTypeInterface;
 
+/**
+ * OAuth 2.0 authentication server class
+ */
 class AuthServer
 {
     /**
@@ -21,14 +33,34 @@ class AuthServer
      */
     protected $scopeDelimeter = ',';
 
+    /**
+     * The TTL (time to live) of an access token in seconds (default: 3600)
+     * @var integer
+     */
     static protected $expiresIn = 3600;
 
+    /**
+     * The registered grant response types
+     * @var array
+     */
     protected $responseTypes = array();
 
+    /**
+     * The client, scope and session storage classes
+     * @var array
+     */
     static protected $storages = array();
 
+    /**
+     * The registered grant types
+     * @var array
+     */
     static protected $grantTypes = array();
 
+    /**
+     * The request object
+     * @var Util\RequestInterface
+     */
     static protected $request = null;
 
     /**
@@ -67,11 +99,24 @@ class AuthServer
         'invalid_refresh'           =>  'The refresh token is invalid.',
     );
 
+    /**
+     * Get an exception message
+     *
+     * @param  string $error The error message key
+     * @return string        The error message
+     */
     public static function getExceptionMessage($error = '')
     {
         return self::$exceptionMessages[$error];
     }
 
+    /**
+     * Create a new OAuth2 authentication server
+     *
+     * @param ClientInterface  $client  A class which inherits from Storage/ClientInterface
+     * @param SessionInterface $session A class which inherits from Storage/SessionInterface
+     * @param ScopeInterface   $scope   A class which inherits from Storage/ScopeInterface
+     */
     public function __construct(ClientInterface $client, SessionInterface $session, ScopeInterface $scope)
     {
         self::$storages = array(
@@ -81,6 +126,11 @@ class AuthServer
         );
     }
 
+    /**
+     * Enable support for a grant
+     * @param GrantTypeInterface $grantType  A grant class which conforms to Interface/GrantTypeInterface
+     * @param null|string        $identifier An identifier for the grant (autodetected if not passed)
+     */
     public function addGrantType(GrantTypeInterface $grantType, $identifier = null)
     {
         if (is_null($identifier)) {
@@ -93,26 +143,49 @@ class AuthServer
         }
     }
 
+    /**
+     * Check if a grant type has been enabled
+     * @param  string  $identifier The grant type identifier
+     * @return boolean             Returns "true" if enabled, "false" if not
+     */
     public static function hasGrantType($identifier)
     {
         return (array_key_exists($identifier, self::$grantTypes));
     }
 
+    /**
+     * Get the scope delimeter
+     *
+     * @return string The scope delimiter (default: ",")
+     */
     public function getScopeDelimeter()
     {
         return $this->scopeDelimeter;
     }
 
-    public function setScopeDelimeter($scope_delimeter)
+    /**
+     * Set the scope delimiter
+     *
+     * @param string $scopeDelimeter
+     */
+    public function setScopeDelimeter($scopeDelimeter)
     {
-        $this->scopeDelimeter = $scope_delimeter;
+        $this->scopeDelimeter = $scopeDelimeter;
     }
 
+    /**
+     * Get the TTL for an access token
+     * @return int The TTL
+     */
     public static function getExpiresIn()
     {
         return self::$expiresIn;
     }
 
+    /**
+     * Set the TTL for an access token
+     * @param int $expiresIn The new TTL
+     */
     public function setExpiresIn($expiresIn)
     {
         self::$expiresIn = $expiresIn;
@@ -121,7 +194,7 @@ class AuthServer
     /**
      * Sets the Request Object
      *
-     * @param  RequestInterface The Request Object
+     * @param Util\RequestInterface The Request Object
      */
     public function setRequest(Util\RequestInterface $request)
     {
@@ -131,7 +204,7 @@ class AuthServer
     /**
      * Gets the Request object.  It will create one from the globals if one is not set.
      *
-     * @return  RequestInterface
+     * @return Util\RequestInterface
      */
     public static function getRequest()
     {
@@ -145,6 +218,11 @@ class AuthServer
         return self::$request;
     }
 
+    /**
+     * Return a storage class
+     * @param  string $obj The class required
+     * @return Storage\ClientInterface|Storage\ScopeInterface|Storage\SessionInterface
+     */
     public static function getStorage($obj)
     {
         return self::$storages[$obj];
@@ -153,8 +231,8 @@ class AuthServer
     /**
      * Check authorise parameters
      *
-     * @access public
      * @param  array $inputParams Optional array of parsed $_GET keys
+     * @throws \OAuth2\Exception\ClientException
      * @return array             Authorise request parameters
      */
     public function checkAuthoriseParams($inputParams = array())
@@ -236,10 +314,10 @@ class AuthServer
     /**
      * Parse a new authorise request
      *
-     * @param  string $type            The session owner's type
+     * @param  string $type        The session owner's type
-     * @param  string $typeId          The session owner's ID
+     * @param  string $typeId      The session owner's ID
-     * @param  array  $authoriseParams The authorise request $_GET parameters
+     * @param  array  $authParams  The authorise request $_GET parameters
-     * @return string                  An authorisation code
+     * @return string              An authorisation code
      */
     public function newAuthoriseRequest($type, $typeId, $authParams = array())
     {
@@ -264,7 +342,6 @@ class AuthServer
     /**
      * Issue an access token
      *
-     * @access public
      * @param  array $inputParams Optional array of parsed $_POST keys
      * @return array             Authorise request parameters
      */
@@ -287,6 +364,11 @@ class AuthServer
         return $this->getGrantType($authParams['grant_type'])->completeFlow($inputParams, $authParams);
     }
 
+    /**
+     * Return a grant type class
+     * @param  string $grantType The grant type identifer
+     * @return class
+     */
     protected function getGrantType($grantType)
     {
         return self::$grantTypes[$grantType];

src/OAuth2/ResourceServer.php

@@ -1,4 +1,13 @@
 <?php
+/**
+ * OAuth 2.0 Resource Server
+ *
+ * @package     lncd/oauth2
+ * @author      Alex Bilbie <hello@alexbilbie.com>
+ * @copyright   Copyright (c) 2013 University of Lincoln
+ * @license     http://mit-license.org/
+ * @link        http://github.com/lncd/oauth2
+ */
 
 namespace OAuth2;
 
@@ -8,29 +17,63 @@ use OAuth2\Storage\SessionScopeInterface;
 use OAuth2\Util\RequestInterface;
 use OAuth2\Util\Request;
 
+/**
+ * OAuth 2.0 Resource Server
+ */
 class ResourceServer
 {
+    /**
+     * The access token
+     * @var string
+     */
     protected $accessToken = null;
 
+    /**
+     * The session ID
+     * @var string
+     */
     protected $sessionId = null;
 
+    /**
+     * The type of the owner of the access token
+     * @var string
+     */
     protected $ownerType = null;
 
+    /**
+     * The ID of the owner of the access token
+     * @var string
+     */
     protected $ownerId = null;
 
+    /**
+     * The scopes associated with the access token
+     * @var array
+     */
     protected $sessionScopes = array();
 
+    /**
+     * The client, scope and session storage classes
+     * @var array
+     */
     protected $storages = array();
 
+    /**
+     * The request object
+     * @var Util\RequestInterface
+     */
     protected $request = null;
 
+    /**
+     * The query string key which is used by clients to present the access token (default: oauth_token)
+     * @var string
+     */
     protected $tokenKey = 'oauth_token';
 
     /**
      * Sets up the Resource
      *
-     * @param  SessionInterface  The Session Storage Object
+     * @param SessionInterface  The Session Storage Object
-     * @param  SessionScopeInterface  The Session Scope Storage Object
      */
     public function __construct(SessionInterface $session)
     {
@@ -50,7 +93,7 @@ class ResourceServer
     /**
      * Gets the Request object.  It will create one from the globals if one is not set.
      *
-     * @return  RequestInterface
+     * @return Util\RequestInterface
      */
     public function getRequest()
     {
@@ -63,20 +106,30 @@ class ResourceServer
         return $this->request;
     }
 
+    /**
+     * Returns the query string key for the access token.
+     *
+     * @return string
+     */
     public function getTokenKey()
     {
         return $this->tokenKey;
     }
 
+    /**
+     * Sets the query string key for the access token.
+     *
+     * @param $key The new query string key
+     */
     public function setTokenKey($key)
     {
         $this->tokenKey = $key;
     }
 
     /**
-     * Gets the Owner ID.
+     * Gets the access token owner ID.
      *
-     * @return  int
+     * @return string
      */
     public function getOwnerId()
     {
@@ -84,9 +137,9 @@ class ResourceServer
     }
 
     /**
-     * Gets the Owner Type.
+     * Gets the owner type.
      *
-     * @return  string
+     * @return string
      */
     public function getOwnerType()
     {
@@ -94,9 +147,9 @@ class ResourceServer
     }
 
     /**
-     * Gets the Access Token.
+     * Gets the access token.
      *
-     * @return  string
+     * @return string
      */
     public function getAccessToken()
     {
@@ -104,8 +157,9 @@ class ResourceServer
     }
 
     /**
-     * Checks if the Access Token is valid or not.
+     * Checks if the access token is valid or not.
      *
+     * @throws Exception\InvalidAccessTokenException Thrown if the presented access token is not valid
      * @return bool
      */
     public function isValid()
@@ -129,9 +183,10 @@ class ResourceServer
     }
 
     /**
-     * Checks if the current session has the given scope(s).
+     * Checks if the presented access token has the given scope(s).
      *
-     * @param   array
+     * @param array|string  An array of scopes or a single scope as a string
+     * @return bool         Returns bool if all scopes are found, false if any fail
      */
     public function hasScope($scopes)
     {
@@ -153,10 +208,10 @@ class ResourceServer
     }
 
     /**
-     * Reads in the Access Token from the headers.
+     * Reads in the access token from the headers.
      *
+     * @throws Exception\MissingAccessTokenException  Thrown if there is no access token presented
      * @return string
-     * @throws Exception\MissingAccessTokenException
      */
     protected function determineAccessToken()
     {