From 958eab33a711cb453198726ac58d082bb9c1926f Mon Sep 17 00:00:00 2001 From: Alex Bilbie Date: Tue, 20 Nov 2012 15:27:33 +0000 Subject: [PATCH] Lots of small documentation updates and clarifications --- src/Oauth2/Authentication/Database.php | 138 ++++++++++++++----------- 1 file changed, 75 insertions(+), 63 deletions(-) diff --git a/src/Oauth2/Authentication/Database.php b/src/Oauth2/Authentication/Database.php index ed526f89..b46a05ec 100644 --- a/src/Oauth2/Authentication/Database.php +++ b/src/Oauth2/Authentication/Database.php @@ -6,30 +6,42 @@ interface Database { /** * Validate a client - * + * * Database query: - * + * * * # Client ID + redirect URI * SELECT clients.id FROM clients LEFT JOIN client_endpoints ON * client_endpoints.client_id = clients.id WHERE clients.id = $clientId AND * client_endpoints.redirect_uri = $redirectUri - * + * * # Client ID + client secret * SELECT clients.id FROM clients WHERE clients.id = $clientId AND * clients.secret = $clientSecret - * + * * # Client ID + client secret + redirect URI * SELECT clients.id FROM clients LEFT JOIN client_endpoints ON * client_endpoints.client_id = clients.id WHERE clients.id = $clientId AND * clients.secret = $clientSecret AND client_endpoints.redirect_uri = * $redirectUri * - * - * @param string $clientId The client's ID + * + * Response: + * + * + * Array + * ( + * [client_id] => (string) The client ID + * [client secret] => (string) The client secret + * [redirect_uri] => (string) The redirect URI used in this request + * [name] => (string) The name of the client + * ) + * + * + * @param string $clientId The client's ID * @param string $clientSecret The client's secret (default = "null") - * @param string $redirectUri The client's redirect URI (default = "null") - * @return [type] [description] + * @param string $redirectUri The client's redirect URI (default = "null") + * @return bool|array Returns false if the validation fails, array on success */ public function validateClient( $clientId, @@ -39,16 +51,16 @@ interface Database /** * Create a new OAuth session - * + * * Database query: - * + * * * INSERT INTO oauth_sessions (client_id, redirect_uri, owner_type, * owner_id, auth_code, access_token, stage, first_requested, last_updated) * VALUES ($clientId, $redirectUri, $type, $typeId, $authCode, * $accessToken, $stage, UNIX_TIMESTAMP(NOW()), UNIX_TIMESTAMP(NOW())) * - * + * * @param string $clientId The client ID * @param string $redirectUri The redirect URI * @param string $type The session owner's type (default = "user") @@ -56,7 +68,7 @@ interface Database * @param string $authCode The authorisation code (default = "null") * @param string $accessToken The access token (default = "null") * @param string $stage The stage of the session (default ="request") - * @return [type] [description] + * @return int The session ID */ public function newSession( $clientId, @@ -71,20 +83,20 @@ interface Database /** * Update an OAuth session - * + * * Database query: - * + * * * UPDATE oauth_sessions SET auth_code = $authCode, access_token = * $accessToken, stage = $stage, last_updated = UNIX_TIMESTAMP(NOW()) WHERE * id = $sessionId * - * + * * @param string $sessionId The session ID * @param string $authCode The authorisation code (default = "null") * @param string $accessToken The access token (default = "null") * @param string $stage The stage of the session (default ="request") - * @return void + * @return void */ public function updateSession( $sessionId, @@ -96,16 +108,16 @@ interface Database /** * Delete an OAuth session - * + * * * DELETE FROM oauth_sessions WHERE client_id = $clientId AND owner_type = * $type AND owner_id = $typeId * - * + * * @param string $clientId The client ID - * @param string $type The session owner's type + * @param string $type The session owner's type * @param string $typeId The session owner's ID - * @return [type] [description] + * @return void */ public function deleteSession( $clientId, @@ -115,16 +127,16 @@ interface Database /** * Validate that an authorisation code is valid - * + * * Database query: - * + * * * SELECT id FROM oauth_sessions WHERE client_id = $clientID AND * redirect_uri = $redirectUri AND auth_code = $authCode * - * + * * Response: - * + * * * Array * ( @@ -141,12 +153,12 @@ interface Database * last updated * ) * - * + * * @param string $clientId The client ID * @param string $redirectUri The redirect URI * @param string $authCode The authorisation code - * @return int|bool Returns the session ID if the auth code - * is valid otherwise returns false + * @return int|bool Returns the session ID if the auth code + * is valid otherwise returns false */ public function validateAuthCode( $clientId, @@ -156,18 +168,18 @@ interface Database /** * Return the session ID for a given session owner and client combination - * + * * Database query: - * + * * * SELECT id FROM oauth_sessions WHERE client_id = $clientId * AND owner_type = $type AND owner_id = $typeId * - * - * @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 $clientId The client ID - * @return string|null Return the session ID as an integer if + * @return string|null Return the session ID as an integer if * found otherwise returns false */ public function hasSession( @@ -178,13 +190,13 @@ interface Database /** * Return the access token for a given session - * + * * Database query: - * + * * * SELECT access_token FROM oauth_sessions WHERE id = $sessionId * - * + * * @param int $sessionId The OAuth session ID * @return string|null Returns the access token as a string if * found otherwise returns null @@ -193,13 +205,13 @@ interface Database /** * Removes an authorisation code associated with a session - * + * * Database query: - * + * * * UPDATE oauth_sessions SET auth_code = NULL WHERE id = $sessionId * - * + * * @param int $sessionId The OAuth session ID * @return void */ @@ -207,14 +219,14 @@ interface Database /** * Sets a sessions access token - * + * * Database query: - * + * * - * UPDATE oauth_sessions SET access_token = $accessToken WHERE id = + * UPDATE oauth_sessions SET access_token = $accessToken WHERE id = * $sessionId * - * + * * @param int $sessionId The OAuth session ID * @param string $accessToken The access token * @return void @@ -226,14 +238,14 @@ interface Database /** * Associates a session with a scope - * + * * Database query: - * + * * - * INSERT INTO oauth_session_scopes (session_id, scope) VALUE ($sessionId, + * INSERT INTO oauth_session_scopes (session_id, scope) VALUE ($sessionId, * $scope) * - * + * * @param int $sessionId The session ID * @param string $scope The scope * @return void @@ -245,15 +257,15 @@ interface Database /** * Return information about a scope - * + * * Database query: - * + * * * SELECT * FROM scopes WHERE scope = $scope * - * + * * Response: - * + * * * Array * ( @@ -263,22 +275,22 @@ interface Database * [description] => (string) The scope's description * ) * - * + * * @param string $scope The scope - * @return array + * @return array */ public function getScope($scope); /** * Associate a session's scopes with an access token - * + * * Database query: - * + * * - * UPDATE oauth_session_scopes SET access_token = $accessToken WHERE + * UPDATE oauth_session_scopes SET access_token = $accessToken WHERE * session_id = $sessionId * - * + * * @param int $sessionId The session ID * @param string $accessToken The access token * @return void @@ -290,17 +302,17 @@ interface Database /** * Return the scopes associated with an access token - * + * * Database query: - * + * * - * SELECT scopes.scope, scopes.name, scopes.description FROM - * oauth_session_scopes JOIN scopes ON oauth_session_scopes.scope = + * SELECT scopes.scope, scopes.name, scopes.description FROM + * oauth_session_scopes JOIN scopes ON oauth_session_scopes.scope = * scopes.scope WHERE access_token = $accessToken * - * + * * Response: - * + * * * Array * ( @@ -312,7 +324,7 @@ interface Database * ) * ) * - * + * * @param string $accessToken The access token * @return array */