Commits

arnaud_lb committed 6667312 Merge

Merge pull request #26 from jasongrimes/update-phpdoc

Update PHPDoc documentation of interfaces.

Comments (0)

Files changed (7)

lib/OAuth2/IOAuth2GrantClient.php

 /**
  * Storage engines that support the "Client Credentials"
  * grant type should implement this interface
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.4
  */
 interface IOAuth2GrantClient extends IOAuth2Storage {
-  
+
     /**
-	 * Required for OAuth2::GRANT_TYPE_CLIENT_CREDENTIALS.
-	 *
-	 * @param IOAuth2Client $client
-	 * Client to be check with.
-	 * @param $client_secret
-	 * (optional) If a secret is required, check that they've given the right one.
-	 *
-	 * @return
-	 * TRUE if the client credentials are valid, and MUST return FALSE if it isn't.
-	 * When using "client credentials" grant mechanism and you want to
-	 * verify the scope of a user's access, return an associative array
-	 * with the scope values as below. We'll check the scope you provide
-	 * against the requested scope before providing an access token:
-	 * @code
-	 * return array(
-	 * 'scope' => <stored scope values (space-separated string)>,
-	 * );
-	 * @endcode
-	 *
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.4.2
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function checkClientCredentialsGrant(IOAuth2Client $client, $client_secret);
+     * Required for OAuth2::GRANT_TYPE_CLIENT_CREDENTIALS.
+     *
+     * @param IOAuth2Client $client
+     * The client for which to check credentials.
+     * @param string $client_secret
+     * (optional) If a secret is required, check that they've given the right one.
+     *
+     * @return
+     * TRUE if the client credentials are valid, and MUST return FALSE if they aren't.
+     * When using "client credentials" grant mechanism and you want to
+     * verify the scope of a user's access, return an associative array
+     * with the scope values as below. We'll check the scope you provide
+     * against the requested scope before providing an access token:
+     * @code
+     * return array(
+     * 'scope' => <stored scope values (space-separated string)>,
+     * );
+     * @endcode
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.4.2
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function checkClientCredentialsGrant(IOAuth2Client $client, $client_secret);
 }

lib/OAuth2/IOAuth2GrantCode.php

 namespace OAuth2;
 
 use OAuth2\Model\IOAuth2Client;
+use OAuth2\Model\IOAuth2AuthCode;
 
 /**
  * Storage engines that support the "Authorization Code"
  * grant type should implement this interface
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.1
  */
 interface IOAuth2GrantCode extends IOAuth2Storage {
-  
-  /**
-   * The Authorization Code grant type supports a response type of "code". 
-   * 
-   * @var string
-   * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.1
-   * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
-   */
-  const RESPONSE_TYPE_CODE = OAuth2::RESPONSE_TYPE_AUTH_CODE;
-  
+
+    /**
+     * The Authorization Code grant type supports a response type of "code".
+     *
+     * @var string
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.1
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
+     */
+    const RESPONSE_TYPE_CODE = OAuth2::RESPONSE_TYPE_AUTH_CODE;
+
     /**
-	 * Fetch authorization code data (probably the most common grant type).
-	 *
-	 * Retrieve the stored data for the given authorization code.
-	 *
-	 * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
-	 *
-	 * @param $code
-	 * Authorization code to be check with.
-	 *
-	 * @return IOAuth2AuthCode
-	 *
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.1
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function getAuthCode($code);
+     * Fetch authorization code data (probably the most common grant type).
+     *
+     * Retrieve the stored data for the given authorization code.
+     *
+     * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
+     *
+     * @param string $code
+     * The authorization code string for which to fetch data.
+     *
+     * @return IOAuth2AuthCode
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.1
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function getAuthCode($code);
 
-	/**
-	 * Take the provided authorization code values and store them somewhere.
-	 *
-	 * This function should be the storage counterpart to getAuthCode().
-	 *
-	 * If storage fails for some reason, we're not currently checking for
-	 * any sort of success/failure, so you should bail out of the script
-	 * and provide a descriptive fail message.
-	 *
-	 * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
-	 *
-	 * @param $code
-	 * Authorization code to be stored.
-	 * @param IOAuth2Client $client
-	 * Client identifier to be stored.
-	 * @param $data
-	 * Application data
-	 * @param $redirect_uri
-	 * Redirect URI to be stored.
-	 * @param $expires
-	 * Expiration to be stored.
-	 * @param $scope
-	 * (optional) Scopes to be stored in space-separated string.
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function createAuthCode($code, IOAuth2Client $client, $data, $redirect_uri, $expires, $scope = NULL);
-	
+    /**
+     * Take the provided authorization code values and store them somewhere.
+     *
+     * This function should be the storage counterpart to getAuthCode().
+     *
+     * If storage fails for some reason, we're not currently checking for
+     * any sort of success/failure, so you should bail out of the script
+     * and provide a descriptive fail message.
+     *
+     * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
+     *
+     * @param string $code
+     * Authorization code string to be stored.
+     * @param IOAuth2Client $client
+     * The client associated with this authorization code.
+     * @param mixed $data
+     * Application data to associate with this authorization code, such as a User object.
+     * @param string $redirect_uri
+     * Redirect URI to be stored.
+     * @param int $expires
+     * The timestamp when the authorization code will expire.
+     * @param string $scope
+     * (optional) Scopes to be stored in space-separated string.
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function createAuthCode($code, IOAuth2Client $client, $data, $redirect_uri, $expires, $scope = NULL);
 }

lib/OAuth2/IOAuth2GrantExtension.php

 /**
  * Storage engines that support the "Extensible"
  * grant types should implement this interface
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.5
  */
 interface IOAuth2GrantExtension extends IOAuth2Storage {
-  
-  /**
-	 * Check any extended grant types.
-     * 
+
+    /**
+     * Check any extended grant types.
+     *
      * @param IOAuth2Client $client
-	 * @param string $uri
-	 * URI of the grant type definition
-	 * @param array $inputData
-	 * Unfiltered input data. The source is *not* guaranteed to be POST (but
-	 * is likely to be).
-	 * @param array $authHeaders
-	 * Authorization headers
-	 * @return
-	 * FALSE if the authorization is rejected or not support.
-	 * TRUE or an associative array if you wantto verify the scope:
-	 * @code
-	 * return array(
-	 * 'scope' => <stored scope values (space-separated string)>,
-	 * );
-	 * @endcode
-	 * 
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.5
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
-	 */
-	public function checkGrantExtension(IOAuth2Client $client, $uri, array $inputData, array $authHeaders);
+     * @param string $uri
+     * URI of the grant type definition
+     * @param array $inputData
+     * Unfiltered input data. The source is *not* guaranteed to be POST (but
+     * is likely to be).
+     * @param array $authHeaders
+     * Authorization headers
+     * @return
+     * FALSE if the authorization is rejected or not support.
+     * TRUE or an associative array if you want to verify the scope:
+     * @code
+     * return array(
+     * 'scope' => <stored scope values (space-separated string)>,
+     * );
+     * @endcode
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.5
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
+     */
+    public function checkGrantExtension(IOAuth2Client $client, $uri, array $inputData, array $authHeaders);
 }

lib/OAuth2/IOAuth2GrantImplicit.php

 /**
  * Storage engines that support the "Implicit"
  * grant type should implement this interface
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
  */
 interface IOAuth2GrantImplicit extends IOAuth2Storage {
 
-  /**
-   * The Implicit grant type supports a response type of "token". 
-   * 
-   * @var string
-   * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.2
-   * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
-   */
-  const RESPONSE_TYPE_TOKEN = OAuth2::RESPONSE_TYPE_ACCESS_TOKEN;
+    /**
+     * The Implicit grant type supports a response type of "token".
+     *
+     * @var string
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.4.2
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.2
+     */
+    const RESPONSE_TYPE_TOKEN = OAuth2::RESPONSE_TYPE_ACCESS_TOKEN;
 }

lib/OAuth2/IOAuth2GrantUser.php

 /**
  * Storage engines that support the "Resource Owner Password Credentials"
  * grant type should implement this interface
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.3
  */
 interface IOAuth2GrantUser extends IOAuth2Storage {
 
- 	/**
-	 * Grant access tokens for basic user credentials.
-	 *
-	 * Check the supplied username and password for validity.
-	 *
-	 * You can also use the $client_id param to do any checks required based
-	 * on a client, if you need that.
-	 *
-	 * Required for OAuth2::GRANT_TYPE_USER_CREDENTIALS.
-	 *
-	 * @param IOAuth2Client $client
-	 * Client to be check with.
-	 * @param $username
-	 * Username to be check with.
-	 * @param $password
-	 * Password to be check with.
-	 *
-	 * @return
-	 * TRUE if the username and password are valid, and FALSE if it isn't.
-	 * Moreover, if the username and password are valid, and you want to
-	 * verify the scope of a user's access, return an associative array
-	 * with the scope values as below. We'll check the scope you provide
-	 * against the requested scope before providing an access token:
-	 * @code
-	 * return array(
-	 * 'scope' => <stored scope values (space-separated string)>,
-	 * );
-	 * @endcode
-	 *
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.3
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function checkUserCredentials(IOAuth2Client $client, $username, $password);
+    /**
+     * Grant access tokens for basic user credentials.
+     *
+     * Check the supplied username and password for validity.
+     *
+     * You can also use the $client param to do any checks required based
+     * on a client, if you need that.
+     *
+     * Required for OAuth2::GRANT_TYPE_USER_CREDENTIALS.
+     *
+     * @param IOAuth2Client $client
+     * Client to check.
+     * @param string $username
+     * Username to check.
+     * @param string $password
+     * Password to check.
+     *
+     * @return
+     * TRUE if the username and password are valid, and FALSE if they aren't.
+     * Moreover, if the username and password are valid, and you want to
+     * verify the scope of a user's access, return an associative array
+     * with the scope values as below. We'll check the scope you provide
+     * against the requested scope before providing an access token:
+     * @code
+     * return array(
+     * 'scope' => <stored scope values (space-separated string)>,
+     * );
+     * @endcode
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-4.3
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function checkUserCredentials(IOAuth2Client $client, $username, $password);
 }

lib/OAuth2/IOAuth2RefreshTokens.php

 namespace OAuth2;
 
 use OAuth2\Model\IOAuth2Client;
+use OAuth2\Model\IOAuth2Token;
 
 /**
  * Storage engines that want to support refresh tokens should
  * implement this interface.
- * 
+ *
  * @author Dave Rochwerger <catch.dave@gmail.com>
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-6
  * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-1.5
  */
 interface IOAuth2RefreshTokens extends IOAuth2Storage {
-  
-  /**
-	 * Grant refresh access tokens.
-	 *
-	 * Retrieve the stored data for the given refresh token.
-	 *
-	 * Required for OAuth2::GRANT_TYPE_REFRESH_TOKEN.
-	 *
-	 * @param $refresh_token
-	 * Refresh token to be check with.
-	 *
-	 * @return
-	 * An associative array as below, and NULL if the refresh_token is
-	 * invalid:
-	 * - client_id: Stored client identifier.
-	 * - expires: Stored expiration unix timestamp.
-	 * - scope: (optional) Stored scope values in space-separated string.
-	 *
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-6
-	 *
-	 * @ingroup oauth2_section_6
-	 */
-	public function getRefreshToken($refresh_token);
 
-	/**
-	 * Take the provided refresh token values and store them somewhere.
-	 *
-	 * This function should be the storage counterpart to getRefreshToken().
-	 *
-	 * If storage fails for some reason, we're not currently checking for
-	 * any sort of success/failure, so you should bail out of the script
-	 * and provide a descriptive fail message.
-	 *
-	 * Required for OAuth2::GRANT_TYPE_REFRESH_TOKEN.
-	 *
-	 * @param $refresh_token
-	 * Refresh token to be stored.
-	 * @param $client_id
-	 * Client identifier to be stored.
-	 * @param $expires
-	 * expires to be stored.
-	 * @param $scope
-	 * (optional) Scopes to be stored in space-separated string.
-	 *
-	 * @ingroup oauth2_section_6
-	 */
-	public function createRefreshToken($refresh_token, IOAuth2Client $client, $data, $expires, $scope = NULL);
+    /**
+     * Grant refresh access tokens.
+     *
+     * Retrieve the stored data for the given refresh token.
+     *
+     * Required for OAuth2::GRANT_TYPE_REFRESH_TOKEN.
+     *
+     * @param string $refresh_token
+     * Refresh token string.
+     *
+     * @return IOAuth2Token
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-6
+     *
+     * @ingroup oauth2_section_6
+     */
+    public function getRefreshToken($refresh_token);
 
-	/**
-	 * Expire a used refresh token.
-	 *
-	 * This is not explicitly required in the spec, but is almost implied.
-	 * After granting a new refresh token, the old one is no longer useful and
-	 * so should be forcibly expired in the data store so it can't be used again.
-	 *
-	 * If storage fails for some reason, we're not currently checking for
-	 * any sort of success/failure, so you should bail out of the script
-	 * and provide a descriptive fail message.
-	 *
-	 * @param $refresh_token
-	 * Refresh token to be expirse.
-	 *
-	 * @ingroup oauth2_section_6
-	 */
-	public function unsetRefreshToken($refresh_token);
+    /**
+     * Take the provided refresh token values and store them somewhere.
+     *
+     * This function should be the storage counterpart to getRefreshToken().
+     *
+     * If storage fails for some reason, we're not currently checking for
+     * any sort of success/failure, so you should bail out of the script
+     * and provide a descriptive fail message.
+     *
+     * Required for OAuth2::GRANT_TYPE_REFRESH_TOKEN.
+     *
+     * @param string $refresh_token
+     * The refresh token string to be stored.
+     * @param IOAuth2Client $client
+     * The client associated with this refresh token.
+     * @param mixed $data
+     * Application data associated with the refresh token, such as a User object.
+     * @param int $expires
+     * The timestamp when the refresh token will expire.
+     * @param string $scope
+     * (optional) Scopes to be stored in space-separated string.
+     *
+     * @ingroup oauth2_section_6
+     */
+    public function createRefreshToken($refresh_token, IOAuth2Client $client, $data, $expires, $scope = NULL);
+
+    /**
+     * Expire a used refresh token.
+     *
+     * This is not explicitly required in the spec, but is almost implied.
+     * After granting a new refresh token, the old one is no longer useful and
+     * so should be forcibly expired in the data store so it can't be used again.
+     *
+     * If storage fails for some reason, we're not currently checking for
+     * any sort of success/failure, so you should bail out of the script
+     * and provide a descriptive fail message.
+     *
+     * @param string $refresh_token
+     * The refresh token string to expire.
+     *
+     * @ingroup oauth2_section_6
+     */
+    public function unsetRefreshToken($refresh_token);
 }

lib/OAuth2/IOAuth2Storage.php

 
 /**
  * All storage engines need to implement this interface in order to use OAuth2 server
- * 
+ *
  * @author David Rochwerger <catch.dave@gmail.com>
  */
 interface IOAuth2Storage {
 
     /**
+     * Get a client by its ID.
+     *
+     * @param string $client_id
      * @return IOAuth2Client
      */
     public function getClient($client_id);
 
-	/**
-	 * Make sure that the client credentials is valid.
-	 * 
-	 * @param $client_id
-	 * Client identifier to be check with.
-	 * @param $client_secret
-	 * (optional) If a secret is required, check that they've given the right one.
-	 *
-	 * @return
-	 * TRUE if the client credentials are valid, and MUST return FALSE if it isn't.
-	 * @endcode
-	 *
-	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-3.1
-	 *
-	 * @ingroup oauth2_section_3
-	 */
-	public function checkClientCredentials(IOAuth2Client $client, $client_secret = NULL);
+    /**
+     * Make sure that the client credentials are valid.
+     *
+     * @param IOAuth2Client $client
+     * The client for which to check credentials.
+     * @param string $client_secret
+     * (optional) If a secret is required, check that they've given the right one.
+     *
+     * @return
+     * TRUE if the client credentials are valid, and MUST return FALSE if they aren't.
+     * @endcode
+     *
+     * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-3.1
+     *
+     * @ingroup oauth2_section_3
+     */
+    public function checkClientCredentials(IOAuth2Client $client, $client_secret = NULL);
 
-	/**
-	 * Look up the supplied oauth_token from storage.
-	 *
-	 * We need to retrieve access token data as we create and verify tokens.
-	 *
-	 * @param $oauth_token
-	 * oauth_token to be check with.
-	 *
-	 * @return IOAuth2AccessToken
-	 *
-	 * @ingroup oauth2_section_7
-	 */
-	public function getAccessToken($oauth_token);
+    /**
+     * Look up the supplied oauth_token from storage.
+     *
+     * We need to retrieve access token data as we create and verify tokens.
+     *
+     * @param string $oauth_token
+     * The token string.
+     *
+     * @return IOAuth2AccessToken
+     *
+     * @ingroup oauth2_section_7
+     */
+    public function getAccessToken($oauth_token);
 
-	/**
-	 * Store the supplied access token values to storage.
-	 *
-	 * We need to store access token data as we create and verify tokens.
-	 *
-	 * @param $oauth_token
-	 * oauth_token to be stored.
-	 * @param $client_id
-	 * Client identifier to be stored.
-	 * @param $user_id
-	 * User identifier to be stored.
-	 * @param $expires
-	 * Expiration to be stored.
-	 * @param $scope
-	 * (optional) Scopes to be stored in space-separated string.
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function createAccessToken($oauth_token, IOAuth2Client $client, $data, $expires, $scope = NULL);
+    /**
+     * Store the supplied access token values to storage.
+     *
+     * We need to store access token data as we create and verify tokens.
+     *
+     * @param string $oauth_token
+     * The access token string to be stored.
+     * @param IOAuth2Client $client
+     * The client associated with this refresh token.
+     * @param mixed $data
+     * Application data associated with the refresh token, such as a User object.
+     * @param int $expires
+     * The timestamp when the refresh token will expire.
+     * @param string $scope
+     * (optional) Scopes to be stored in space-separated string.
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function createAccessToken($oauth_token, IOAuth2Client $client, $data, $expires, $scope = NULL);
 
-	/**
-	 * Check restricted grant types of corresponding client identifier.
-	 *
-	 * If you want to restrict clients to certain grant types, override this
-	 * function.
-	 *
-	 * @param IOAuth2Client $client
-	 * Client to be check with.
-	 * @param $grant_type
-	 * Grant type to be check with, would be one of the values contained in
-	 * OAuth2::GRANT_TYPE_REGEXP.
-	 *
-	 * @return
-	 * TRUE if the grant type is supported by this client identifier, and
-	 * FALSE if it isn't.
-	 *
-	 * @ingroup oauth2_section_4
-	 */
-	public function checkRestrictedGrantType(IOAuth2Client $client, $grant_type);
+    /**
+     * Check restricted grant types of corresponding client identifier.
+     *
+     * If you want to restrict clients to certain grant types, override this
+     * function.
+     *
+     * @param IOAuth2Client $client
+     * Client to check.
+     * @param string $grant_type
+     * Grant type to check. One of the values contained in OAuth2::GRANT_TYPE_REGEXP.
+     *
+     * @return
+     * TRUE if the grant type is supported by this client identifier, and
+     * FALSE if it isn't.
+     *
+     * @ingroup oauth2_section_4
+     */
+    public function checkRestrictedGrantType(IOAuth2Client $client, $grant_type);
 }