From 3ab685f8e36299c91c73c3b19c5fc27250ed9a05 Mon Sep 17 00:00:00 2001 From: Alex Bilbie Date: Mon, 16 Jul 2012 18:11:50 +0100 Subject: [PATCH] Updated docblocks for almost all of the methods --- src/oauth2server/DatabaseInterface.php | 180 ++++++++++++++++++++----- 1 file changed, 149 insertions(+), 31 deletions(-) diff --git a/src/oauth2server/DatabaseInterface.php b/src/oauth2server/DatabaseInterface.php index 2bc70808..7f601c3c 100644 --- a/src/oauth2server/DatabaseInterface.php +++ b/src/oauth2server/DatabaseInterface.php @@ -71,11 +71,37 @@ interface DatabaseInteface ); /** - * [validateAuthCode description] - * @param string $clientId The client ID - * @param string $redirectUri The redirect URI - * @param string $authCode The authorisation code - * @return [type] [description] + * Validate that an authorisation code is valid + * + * Database query: + * + * + * SELECT * FROM oauth_sessions WHERE client_id = $clientID AND + * redirect_uri = $redirectUri AND auth_code = $authCode + * + * + * Response: + * + * + * 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 + * ) + * + * + * @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] - * @param string $type The session owner's type - * @param string $typeId The session owner's ID - * @param string $clientId The client ID - * @return boolean [description] + * Return the access token for a given session owner and client combination + * + * Database query: + * + * + * SELECT access_token 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 $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] - * @param int $sessionId The OAuth session ID - * @return [type] [description] + * 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 */ public function getAccessToken($sessionId); /** - * [removeAuthCode description] + * 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 [type] [description] + * @return void */ public function removeAuthCode($sessionId); /** - * [setAccessToken description] + * Sets a sessions access token + * + * Database query: + * + * + * 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 */ public function setAccessToken( - int $sessionId, + $sessionId, $accessToken ); /** - * [addSessionScope description] - * @param int $sessionId [description] - * @param string $scope [description] + * Associates a session with a scope + * + * Database query: + * + * + * INSERT INTO oauth_session_scopes (session_id, scope) VALUE ($sessionId, + * $scope) + * + * + * @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] - * @param string $scope [description] - * @return [type] [description] + * Return information about a scope + * + * Database query: + * + * + * SELECT * FROM scopes WHERE scope = $scope + * + * + * Response: + * + * + * Array + * ( + * [id] => (int) The scope's ID + * [scope] => (string) The scope itself + * [name] => (string) The scope's name + * [description] => (string) The scope's description + * ) + * + * + * @param string $scope The scope + * @return array */ public function getScope($scope); /** - * [updateSessionScopeAccessToken description] - * @param int $sesstionId [description] - * @param string $accessToken [description] - * @return [type] [description] + * Associate a session's scopes with an access token + * + * Database query: + * + * + * 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 */ public function updateSessionScopeAccessToken( - $sesstionId, + $sessionId, $accessToken ); /** - * [accessTokenScopes description] - * @param string $accessToken [description] - * @return [type] [description] + * 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 = + * scopes.scope WHERE access_token = $accessToken + * + * + * Response: + * + * + * Array + * ( + * [0] => Array + * ( + * [scope] => (string) The scope + * [name] => (string) The scope's name + * [description] => (string) The scope's description + * ) + * ) + * + * + * @param string $accessToken The access token + * @return array */ public function accessTokenScopes($accessToken); } \ No newline at end of file