PHPDoc improvements and type hinting of variables. (#828)

bshaffer · May 1, 2017 · 5abe923 · 5abe923
1 parent 5df6668
commit 5abe923
Show file tree

Hide file tree

Showing 54 changed files with 1,904 additions and 479 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -87,7 +87,7 @@ To get the diff for a specific change, go to https://github.com/bshaffer/oauth2-
   * bug #346 Fixes open_basedir warning
   * bug #351 Adds OpenID Connect support
   * bug #355 Adds php 5.6 and HHVM to travis.ci testing
-  * [BC] bug #358 Adds `getQuerystringIdentifier()` to the GrantType interface
+  * [BC] bug #358 Adds `getQueryStringIdentifier()` to the GrantType interface
   * bug #363 Encryption\JWT - Allows for subclassing JWT Headers
   * bug #349 Bearer Tokens - adds requestHasToken method for when access tokens are optional
   * bug #301 Encryption\JWT - fixes urlSafeB64Encode(): ensures newlines are replaced as expected

diff --git a/src/OAuth2/Autoloader.php b/src/OAuth2/Autoloader.php
@@ -10,15 +10,22 @@
  */
 class Autoloader
 {
+    /**
+     * @var string
+     */
     private $dir;
 
+    /**
+     * @param string $dir
+     */
     public function __construct($dir = null)
     {
         if (is_null($dir)) {
             $dir = dirname(__FILE__).'/..';
         }
         $this->dir = $dir;
     }
+
     /**
      * Registers OAuth2\Autoloader as an SPL autoloader.
      */
@@ -31,9 +38,8 @@ public static function register($dir = null)
     /**
      * Handles autoloading of classes.
      *
-     * @param string $class A class name.
-     *
-     * @return boolean Returns true if the class has been loaded
+     * @param string $class - A class name.
+     * @return boolean      - Returns true if the class has been loaded
      */
     public function autoload($class)
     {

diff --git a/src/OAuth2/ClientAssertionType/ClientAssertionTypeInterface.php b/src/OAuth2/ClientAssertionType/ClientAssertionTypeInterface.php
@@ -10,6 +10,19 @@
  */
 interface ClientAssertionTypeInterface
 {
+    /**
+     * Validate the OAuth request
+     *
+     * @param RequestInterface $request
+     * @param ResponseInterface $response
+     * @return mixed
+     */
     public function validateRequest(RequestInterface $request, ResponseInterface $response);
+
+    /**
+     * Get the client id
+     *
+     * @return mixed
+     */
     public function getClientId();
 }
diff --git a/src/OAuth2/ClientAssertionType/HttpBasic.php b/src/OAuth2/ClientAssertionType/HttpBasic.php
@@ -5,6 +5,7 @@
 use OAuth2\Storage\ClientCredentialsInterface;
 use OAuth2\RequestInterface;
 use OAuth2\ResponseInterface;
+use LogicException;
 
 /**
  * Validate a client via Http Basic authentication
@@ -19,14 +20,16 @@ class HttpBasic implements ClientAssertionTypeInterface
     protected $config;
 
     /**
-     * @param OAuth2\Storage\ClientCredentialsInterface $clientStorage REQUIRED Storage class for retrieving client credentials information
-     * @param array                                     $config        OPTIONAL Configuration options for the server
-     *                                                                 <code>
-     *                                                                 $config = array(
-     *                                                                 'allow_credentials_in_request_body' => true, // whether to look for credentials in the POST body in addition to the Authorize HTTP Header
-     *                                                                 'allow_public_clients'  => true              // if true, "public clients" (clients without a secret) may be authenticated
-     *                                                                 );
-     *                                                                 </code>
+     * Config array $config should look as follows:
+     * @code
+     *     $config = array(
+     *         'allow_credentials_in_request_body' => true, // whether to look for credentials in the POST body in addition to the Authorize HTTP Header
+     *         'allow_public_clients'  => true              // if true, "public clients" (clients without a secret) may be authenticated
+     *     );
+     * @endcode
+     *
+     * @param ClientCredentialsInterface $storage Storage
+     * @param array                      $config  Configuration options for the server
      */
     public function __construct(ClientCredentialsInterface $storage, array $config = array())
     {
@@ -37,14 +40,22 @@ public function __construct(ClientCredentialsInterface $storage, array $config =
         ), $config);
     }
 
+    /**
+     * Validate the OAuth request
+     *
+     * @param RequestInterface $request
+     * @param ResponseInterface $response
+     * @return bool|mixed
+     * @throws LogicException
+     */
     public function validateRequest(RequestInterface $request, ResponseInterface $response)
     {
         if (!$clientData = $this->getClientCredentials($request, $response)) {
             return false;
         }
 
         if (!isset($clientData['client_id'])) {
-            throw new \LogicException('the clientData array must have "client_id" set');
+            throw new LogicException('the clientData array must have "client_id" set');
         }
 
         if (!isset($clientData['client_secret']) || $clientData['client_secret'] == '') {
@@ -70,6 +81,11 @@ public function validateRequest(RequestInterface $request, ResponseInterface $re
         return true;
     }
 
+    /**
+     * Get the client id
+     *
+     * @return mixed
+     */
     public function getClientId()
     {
         return $this->clientData['client_id'];
@@ -82,13 +98,14 @@ public function getClientId()
      * According to the spec (draft 20), the client_id can be provided in
      * the Basic Authorization header (recommended) or via GET/POST.
      *
-     * @return
-     * A list containing the client identifier and password, for example
+     * @param RequestInterface  $request
+     * @param ResponseInterface $response
+     * @return array|null A list containing the client identifier and password, for example:
      * @code
-     * return array(
-     *     "client_id"     => CLIENT_ID,        // REQUIRED the client id
-     *     "client_secret" => CLIENT_SECRET,    // OPTIONAL the client secret (may be omitted for public clients)
-     * );
+     *     return array(
+     *         "client_id"     => CLIENT_ID,        // REQUIRED the client id
+     *         "client_secret" => CLIENT_SECRET,    // OPTIONAL the client secret (may be omitted for public clients)
+     *     );
      * @endcode
      *
      * @see http://tools.ietf.org/html/rfc6749#section-2.3.1
@@ -108,7 +125,6 @@ public function getClientCredentials(RequestInterface $request, ResponseInterfac
                  * client_secret can be null if the client's password is an empty string
                  * @see http://tools.ietf.org/html/rfc6749#section-2.3.1
                  */
-
                 return array('client_id' => $request->request('client_id'), 'client_secret' => $request->request('client_secret'));
             }
         }