Updated docblocks for almost all of the methods

src/oauth2server/DatabaseInterface.php

@@ -71,11 +71,37 @@ interface DatabaseInteface
     );
 
     /**
-     * [validateAuthCode description]
+     * Validate that an authorisation code is valid
-     * @param  string $clientId    The client ID
+     * 
-     * @param  string $redirectUri The redirect URI
+     * Database query:
-     * @param  string $authCode    The authorisation code
+     * 
-     * @return [type]              [description]
+     * <code>
+     * SELECT * FROM oauth_sessions WHERE client_id = $clientID AND
+     *  redirect_uri = $redirectUri AND auth_code = $authCode
+     * </code>
+     * 
+     * Response:
+     * 
+     * <code>
+     * Array
+     * (
+     *     [id] => (int) The session ID
+     *     [client_id] => (string) The client ID
+     *     [redirect_uri] => (string) The redirect URI
+     *     [owner_type] => (string) The session owner type
+     *     [owner_id] => (string) The session owner's ID
+     *     [auth_code] => (string) The authorisation code
+     *     [stage] => (string) The session's stage
+     *     [first_requested] => (int) Unix timestamp of the time the session was first generated
+     *     [last_updated] => (int) Unix timestamp of the time the session was last updated
+     * )
+     * </code>
+     * 
+     * @param  string     $clientId    The client ID
+     * @param  string     $redirectUri The redirect URI
+     * @param  string     $authCode    The authorisation code
+     * @return array|null              Returns an array if the authorisation
+     *  code is valid otherwise returns null  
      */
     public function validateAuthCode(
         $clientId,
@@ -84,11 +110,20 @@ interface DatabaseInteface
     );
 
     /**
-     * [hasAccessToken description]
+     * Return the access token for a given session owner and client combination
-     * @param  string  $type     The session owner's type 
+     * 
-     * @param  string  $typeId   The session owner's ID
+     * Database query:
-     * @param  string  $clientId The client ID
+     * 
-     * @return boolean           [description]
+     * <code>
+     * SELECT access_token FROM oauth_sessions WHERE client_id = $clientId
+     *  AND owner_type = $type AND owner_id = $typeId
+     * </code>
+     * 
+     * @param  string      $type     The session owner's type 
+     * @param  string      $typeId   The session owner's ID
+     * @param  string      $clientId The client ID
+     * @return string|null           Return the access token as a string if 
+     *  found otherwise returns null
      */
     public function hasAccessToken(
         $type,
@@ -97,33 +132,66 @@ interface DatabaseInteface
     );
 
     /**
-     * [getAccessToken description]
+     * Return the access token for a given session
-     * @param  int    $sessionId The OAuth session ID
+     * 
-     * @return [type]            [description]
+     * Database query:
+     * 
+     * <code>
+     * SELECT access_token FROM oauth_sessions WHERE id = $sessionId
+     * </code>
+     * 
+     * @param  int         $sessionId The OAuth session ID
+     * @return string|null            Returns the access token as a string if
+     *  found otherwise returns null
      */
     public function getAccessToken($sessionId);
 
     /**
-     * [removeAuthCode description]
+     * Removes an authorisation code associated with a session
+     * 
+     * Database query:
+     * 
+     * <code>
+     * UPDATE oauth_sessions SET auth_code = NULL WHERE id = $sessionId
+     * </code>
+     * 
      * @param  int    $sessionId The OAuth session ID
-     * @return [type]            [description]
+     * @return void
      */
     public function removeAuthCode($sessionId);
 
     /**
-     * [setAccessToken description]
+     * Sets a sessions access token
+     * 
+     * Database query:
+     * 
+     * <code>
+     * UPDATE oauth_sessions SET access_token = $accessToken WHERE id = 
+     *  $sessionId
+     * </code>
+     * 
      * @param int    $sessionId   The OAuth session ID
      * @param string $accessToken The access token
+     * @return void
      */
     public function setAccessToken(
-        int $sessionId,
+        $sessionId,
         $accessToken
     );
 
     /**
-     * [addSessionScope description]
+     * Associates a session with a scope
-     * @param int    $sessionId [description]
+     * 
-     * @param string $scope     [description]
+     * Database query:
+     * 
+     * <code>
+     * INSERT INTO oauth_session_scopes (session_id, scope) VALUE ($sessionId, 
+     *  $scope)
+     * </code>
+     * 
+     * @param int    $sessionId The session ID
+     * @param string $scope     The scope
+     * @return void
      */
     public function addSessionScope(
         $sessionId,
@@ -131,27 +199,77 @@ interface DatabaseInteface
     );
 
     /**
-     * [getScope description]
+     * Return information about a scope
-     * @param  string $scope [description]
+     * 
-     * @return [type]        [description]
+     * Database query:
+     * 
+     * <code>
+     * SELECT * FROM scopes WHERE scope = $scope
+     * </code>
+     * 
+     * Response:
+     * 
+     * <code>
+     * Array
+     * (
+     *     [id] => (int) The scope's ID
+     *     [scope] => (string) The scope itself
+     *     [name] => (string) The scope's name
+     *     [description] => (string) The scope's description
+     * )
+     * </code>
+     * 
+     * @param  string $scope The scope
+     * @return array         
      */
     public function getScope($scope);
 
     /**
-     * [updateSessionScopeAccessToken description]
+     * Associate a session's scopes with an access token
-     * @param  int    $sesstionId  [description]
+     * 
-     * @param  string $accessToken [description]
+     * Database query:
-     * @return [type]              [description]
+     * 
+     * <code>
+     * UPDATE oauth_session_scopes SET access_token = $accessToken WHERE 
+     *  session_id = $sessionId
+     * </code>
+     * 
+     * @param  int    $sessionId   The session ID
+     * @param  string $accessToken The access token
+     * @return void
      */
     public function updateSessionScopeAccessToken(
-        $sesstionId,
+        $sessionId,
         $accessToken
     );
 
     /**
-     * [accessTokenScopes description]
+     * Return the scopes associated with an access token
-     * @param  string $accessToken [description]
+     * 
-     * @return [type]              [description]
+     * Database query:
+     * 
+     * <code>
+     * SELECT scopes.scope, scopes.name, scopes.description FROM 
+     * oauth_session_scopes JOIN scopes ON oauth_session_scopes.scope = 
+     *  scopes.scope WHERE access_token = $accessToken
+     * </code>
+     * 
+     * Response:
+     * 
+     * <code>
+     * Array
+     * (
+     *     [0] => Array
+     *         (
+     *             [scope] => (string) The scope
+     *             [name] => (string) The scope's name
+     *             [description] => (string) The scope's description
+     *         )
+     * )
+     * </code>
+     * 
+     * @param  string $accessToken The access token
+     * @return array
      */
     public function accessTokenScopes($accessToken);
 }