Added example queries and expected responses

src/League/OAuth2/Server/Storage/SessionInterface.php

@@ -15,6 +15,14 @@ interface SessionInterface
 {
     /**
      * Create a new session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * INSERT INTO oauth_sessions (client_id, owner_type,  owner_id)
+     *  VALUE (:clientId, :ownerType, :ownerId)
+     * </code>
+     *
      * @param  string $clientId  The client ID
      * @param  string $ownerType The type of the session owner (e.g. "user")
      * @param  string $ownerId   The ID of the session owner (e.g. "123")
@@ -24,6 +32,13 @@ interface SessionInterface
 
     /**
      * Delete a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * DELETE FROM oauth_sessions WHERE client_id = :clientId AND owner_type = :type AND owner_id = :typeId
+     * </code>
+     *
      * @param  string $clientId  The client ID
      * @param  string $ownerType The type of the session owner (e.g. "user")
      * @param  string $ownerId   The ID of the session owner (e.g. "123")
@@ -33,6 +48,13 @@ interface SessionInterface
 
     /**
      * Associate a redirect URI with a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * INSERT INTO oauth_session_redirects (session_id, redirect_uri) VALUE (:sessionId, :redirectUri)
+     * </code>
+     *
      * @param  int    $sessionId   The session ID
      * @param  string $redirectUri The redirect URI
      * @return void
@@ -41,6 +63,14 @@ interface SessionInterface
 
     /**
      * Associate an access token with a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * INSERT INTO oauth_session_access_tokens (session_id, access_token, access_token_expires)
+     *  VALUE (:sessionId, :accessToken, :accessTokenExpire)
+     * </code>
+     *
      * @param  int    $sessionId   The session ID
      * @param  string $accessToken The access token
      * @param  int    $expireTime  Unix timestamp of the access token expiry time
@@ -50,6 +80,14 @@ interface SessionInterface
 
     /**
      * Associate a refresh token with a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * oauth_session_refresh_tokens (session_access_token_id, refresh_token, refresh_token_expires)
+     *  VALUE (:accessTokenId, :refreshToken, :expireTime)
+     * </code>
+     *
      * @param  int    $accessTokenId The access token ID
      * @param  string $refreshToken  The refresh token
      * @param  int    $expireTime    Unix timestamp of the refresh token expiry time
@@ -59,6 +97,14 @@ interface SessionInterface
 
     /**
      * Assocate an authorization code with a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * INSERT INTO oauth_session_authcodes (session_id, auth_code, auth_code_expires, scope_ids)
+     *  VALUE (:sessionId, :authCode, :authCodeExpires, :scopeIds)
+     * </code>
+     *
      * @param  int    $sessionId  The session ID
      * @param  string $authCode   The authorization code
      * @param  int    $expireTime Unix timestamp of the access token expiry time
@@ -69,6 +115,13 @@ interface SessionInterface
 
     /**
      * Remove an associated authorization token from a session
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * DELETE FROM oauth_session_authcodes WHERE session_id = :sessionId
+     * </code>
+     *
      * @param  int    $sessionId   The session ID
      * @return void
      */
@@ -76,29 +129,96 @@ interface SessionInterface
 
     /**
      * Validate an authorization code
-     * @param  string $clientId    The client ID
+     *
-     * @param  string $redirectUri The redirect URI
+     * Example SQL query:
-     * @param  string $authCode    The authorization code
+     *
-     * @return void
+     * <code>
+     * SELECT oauth_sessions.id, oauth_session_authcodes.scope_ids FROM oauth_sessions
+     *  JOIN oauth_session_authcodes ON oauth_session_authcodes.`session_id` = oauth_sessions.id
+     *  JOIN oauth_session_redirects ON oauth_session_redirects.`session_id` = oauth_sessions.id WHERE
+     * oauth_sessions.client_id = :clientId AND oauth_session_authcodes.`auth_code` = :authCode
+     *  AND `oauth_session_authcodes`.`auth_code_expires` >= :time AND
+     *  `oauth_session_redirects`.`redirect_uri` = :redirectUri
+     * </code>
+     *
+     * Expected response:
+     *
+     * <code>
+     * array(
+     *     'id' =>  (int), // the session ID
+     *     'scope_ids'  =>  (string)
+     * )
+     * </code>
+     *
+     * @param  string     $clientId    The client ID
+     * @param  string     $redirectUri The redirect URI
+     * @param  string     $authCode    The authorization code
+     * @return array|bool              False if invalid or array as above
      */
     public function validateAuthCode($clientId, $redirectUri, $authCode);
 
     /**
      * Validate an access token
-     * @param  string $accessToken [description]
+     *
-     * @return void
+     * Example SQL query:
+     *
+     * <code>
+     * SELECT session_id, oauth_sessions.`client_id`, oauth_sessions.`owner_id`, oauth_sessions.`owner_type`
+     *  FROM `oauth_session_access_tokens` JOIN oauth_sessions ON oauth_sessions.`id` = session_id WHERE
+     *  access_token = :accessToken AND access_token_expires >= UNIX_TIMESTAMP(NOW())
+     * </code>
+     *
+     * Expected response:
+     *
+     * <code>
+     * array(
+     *     'session_id' =>  (int),
+     *     'client_id'  =>  (string),
+     *     'owner_id'   =>  (string),
+     *     'owner_type' =>  (string)
+     * )
+     * </code>
+     *
+     * @param  string     $accessToken The access token
+     * @return array|bool              False if invalid or an array as above
      */
     public function validateAccessToken($accessToken);
 
     /**
      * Validate a refresh token
-     * @param  string $refreshToken The access token
+     *
-     * @return void
+     * Example SQL query:
+     *
+     * <code>
+     * SELECT session_access_token_id FROM `oauth_session_refresh_tokens` WHERE refresh_token = :refreshToken
+     *  AND refresh_token_expires >= UNIX_TIMESTAMP(NOW())
+     * </code>
+     *
+     * @param  string   $refreshToken The access token
+     * @return int|bool               The ID of the access token the refresh token is linked to (or false if invalid)
      */
     public function validateRefreshToken($refreshToken);
 
     /**
      * Get an access token by ID
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * SELECT * FROM `oauth_session_access_tokens` WHERE `id` = :accessTokenId
+     * </code>
+     *
+     * Expected response:
+     *
+     * <code>
+     * array(
+     *     'id' =>  (int),
+     *     'session_id' =>  (int),
+     *     'access_token'   =>  (string),
+     *     'access_token_expires'   =>  (int)
+     * )
+     * </code>
+     *
      * @param  int    $accessTokenId The access token ID
      * @return array
      */
@@ -106,6 +226,13 @@ interface SessionInterface
 
     /**
      * Associate a scope with an access token
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * INSERT INTO `oauth_session_token_scopes` (`session_access_token_id`, `scope_id`) VALUE (:accessTokenId, :scopeId)
+     * </code>
+     *
      * @param  int    $accessTokenId The ID of the access token
      * @param  int    $scopeId       The ID of the scope
      * @return void
@@ -114,6 +241,30 @@ interface SessionInterface
 
     /**
      * Get all associated access tokens for an access token
+     *
+     * Example SQL query:
+     *
+     * <code>
+     * SELECT oauth_scopes.* FROM oauth_session_token_scopes JOIN oauth_session_access_tokens
+     *  ON oauth_session_access_tokens.`id` = `oauth_session_token_scopes`.`session_access_token_id`
+     *  JOIN oauth_scopes ON oauth_scopes.id = `oauth_session_token_scopes`.`scope_id`
+     *  WHERE access_token = :accessToken
+     * </code>
+     *
+     * Expected response:
+     *
+     * <code>
+     * array (
+     *     array(
+     *         'key'    =>  (string),
+     *         'name'   =>  (string),
+     *         'description'    =>  (string)
+     *     ),
+     *     ...
+     *     ...
+     * )
+     * </code>
+     *
      * @param  string $accessToken The access token
      * @return array
      */