Commits

Jason Grimes  committed 1e16f3f

Update PHPDoc documentation of interfaces.

  • Participants
  • Parent commits e56ce04

Comments (0)

Files changed (6)

File lib/OAuth2/IOAuth2GrantClient.php

 	 * Required for OAuth2::GRANT_TYPE_CLIENT_CREDENTIALS.
 	 *
 	 * @param IOAuth2Client $client
-	 * Client to be check with.
-	 * @param $client_secret
+	 * 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 it isn't.
+	 * 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

File 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". 
-   * 
+   * 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).
 	 *
 	 *
 	 * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
 	 *
-	 * @param $code
-	 * Authorization code to be check with.
+     * @param string $code
+     * The authorization code string for which to fetch data.
 	 *
 	 * @return IOAuth2AuthCode
 	 *
 	 *
 	 * Required for OAuth2::GRANT_TYPE_AUTH_CODE.
 	 *
-	 * @param $code
-	 * Authorization code to be stored.
+	 * @param string $code
+	 * Authorization code string to be stored.
 	 * @param IOAuth2Client $client
-	 * Client identifier to be stored.
-	 * @param $data
-	 * Application data
-	 * @param $redirect_uri
+	 * 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 $expires
-	 * Expiration to be stored.
-	 * @param $scope
+	 * @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);
-	
+
 }

File lib/OAuth2/IOAuth2GrantExtension.php

 	 * Authorization headers
 	 * @return
 	 * FALSE if the authorization is rejected or not support.
-	 * TRUE or an associative array if you wantto verify the scope:
+	 * TRUE or an associative array if you want to verify the scope:
 	 * @code
 	 * return array(
 	 * 'scope' => <stored scope values (space-separated string)>,

File lib/OAuth2/IOAuth2GrantUser.php

 	 *
 	 * Check the supplied username and password for validity.
 	 *
-	 * You can also use the $client_id param to do any checks required based
+	 * 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 be check with.
-	 * @param $username
-	 * Username to be check with.
-	 * @param $password
-	 * Password to be check with.
+	 * 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 it isn't.
+	 * 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

File lib/OAuth2/IOAuth2RefreshTokens.php

 namespace OAuth2;
 
 use OAuth2\Model\IOAuth2Client;
+use OAuth2\Model\IOAuth2Token;
 
 /**
  * Storage engines that want to support refresh tokens should
  */
 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.
+	 * @param string $refresh_token
+	 * Refresh token string.
 	 *
-	 * @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.
+	 * @return IOAuth2Token
 	 *
 	 * @see http://tools.ietf.org/html/draft-ietf-oauth-v2-20#section-6
 	 *
 	 *
 	 * 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
+	 * @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);
+    public function createRefreshToken($refresh_token, IOAuth2Client $client, $data, $expires, $scope = NULL);
 
 	/**
 	 * Expire a used refresh token.
 	 * 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.
+	 * @param string $refresh_token
+	 * The refresh token string to expire.
 	 *
 	 * @ingroup oauth2_section_6
 	 */

File lib/OAuth2/IOAuth2Storage.php

 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.
+	 * Make sure that the client credentials are valid.
 	 * 
-	 * @param $client_id
-	 * Client identifier to be check with.
-	 * @param $client_secret
+	 * @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 it isn't.
+	 * 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
 	 *
 	 * We need to retrieve access token data as we create and verify tokens.
 	 *
-	 * @param $oauth_token
-	 * oauth_token to be check with.
+	 * @param string $oauth_token
+	 * The token string.
 	 *
 	 * @return IOAuth2AccessToken
 	 *
 	 *
 	 * 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.
+	 * @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
 	 */
 	 * 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.
+	 * 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