Adding pagination, tests, and docs to Client Grants; minor test suite…

… refactoring

composer.json

@@ -35,7 +35,8 @@
   "scripts": {
     "test": "SHELL_INTERACTIVE=1 vendor/bin/phpunit  --colors=always --verbose ",
     "test-ci": "vendor/bin/phpunit --coverage-text --coverage-clover=build/coverage.xml",
-    "phpcs": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcs --standard=phpcs-ruleset.xml -s",
+    "phpcs": "./vendor/bin/phpcs --standard=phpcs-ruleset.xml -s .",
+    "phpcs-path": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcs --standard=phpcs-ruleset.xml -s",
     "phpcbf": "./vendor/bin/phpcbf --standard=phpcs-ruleset.xml .",
     "phpcbf-path": "SHELL_INTERACTIVE=1 ./vendor/bin/phpcbf --standard=phpcs-ruleset.xml",
     "sniffs": "./vendor/bin/phpcs --standard=phpcs-ruleset.xml -e"

phpcs-ruleset.xml

@@ -61,10 +61,12 @@
         <exclude name="Squiz.Commenting.FileComment"/>
         <exclude name="Squiz.Commenting.LongConditionClosingComment"/>
         <exclude name="Squiz.Commenting.FunctionComment.ScalarTypeHintMissing"/>
+        <exclude name="Squiz.Commenting.FunctionCommentThrowTag.WrongNumber"/>
     </rule>
     <rule ref="Squiz.ControlStructures"/>
     <rule ref="Squiz.Functions">
         <exclude name="Squiz.Functions.MultiLineFunctionDeclaration.NewlineBeforeOpenBrace"/>
+        <exclude name="Squiz.ControlStructures.InlineIfDeclaration.NoBrackets"/>
     </rule>
     <rule ref="Squiz.Functions.FunctionDeclarationArgumentSpacing">
         <properties>
@@ -75,7 +77,10 @@
         <exclude name="Squiz.Operators.ComparisonOperatorUsage.NotAllowed"/>
         <exclude name="Squiz.Operators.ComparisonOperatorUsage.ImplicitTrue"/>
     </rule>
-    <rule ref="Squiz.PHP"/>
+    <rule ref="Squiz.PHP">
+        <exclude name="Squiz.PHP.DisallowComparisonAssignment.AssignedComparison"/>
+        <exclude name="Squiz.PHP.DisallowInlineIf.Found"/>
+    </rule>
     <rule ref="Squiz.Scope"/>
     <rule ref="Squiz.Strings"/>
     <rule ref="Squiz.WhiteSpace">

src/API/Management/ClientGrants.php

@@ -2,75 +2,193 @@
 
 namespace Auth0\SDK\API\Management;
 
-use Auth0\SDK\API\Header\ContentType;
+use Auth0\SDK\Exception\CoreException;
 
+/**
+ * Class ClientGrants.
+ * Handles requests to the Client Grants endpoint of the v2 Management API.
+ *
+ * @package Auth0\SDK\API\Management
+ */
 class ClientGrants extends GenericResource
 {
+
     /**
+     * Get all Client Grants, by page if desired.
+     * Required scope: "read:client_grants"
+     *
+     * @param array        $params   Additional URL parameters to send:
+     *      - "audience" to filter be a specific API audience identifier.
+     *      - "client_id" to return an object.
+     *      - "include_totals" to return an object.
+     * @param null|integer $page     The page number, zero based.
+     * @param null|integer $per_page The amount of entries per page.
      *
-     * @param  string      $id
-     * @param  null|string $audience
      * @return mixed
+     *
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants
      */
-    public function get($id, $audience = null)
+    public function getAll(array $params = [], $page = null, $per_page = null)
     {
-        $request = $this->apiClient->get()
-        ->addPath('client-grants');
+        if (null !== $page) {
+            $params['page'] = abs(intval($page));
+        }
 
-        if ($audience !== null) {
-            $request = $request->withParam('audience', $audience);
+        if (null !== $per_page) {
+            $params['per_page'] = abs(intval($per_page));
         }
 
-        return $request->call();
+        return $this->apiClient->method('get')
+            ->addPath('client-grants')
+            ->withDictParams($params)
+            ->call();
+    }
+
+    /**
+     * Get Client Grants by audience.
+     * Required scope: "read:client_grants"
+     *
+     * @param string       $audience API Audience to filter by.
+     * @param null|integer $page     The page number, zero based.
+     * @param null|integer $per_page The amount of entries per page.
+     *
+     * @return mixed
+     *
+     * @throws CoreException Thrown when $audience is empty or not a string.
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants
+     */
+    public function getByAudience($audience, $page = null, $per_page = null)
+    {
+        if (empty($audience) || ! is_string($audience)) {
+            throw new CoreException('Empty or invalid "audience" parameter.');
+        }
+
+        return $this->getAll(['audience' => $audience], $page, $per_page);
+    }
+
+    /**
+     * Get Client Grants by Client ID.
+     * Required scope: "read:client_grants"
+     *
+     * @param string       $client_id Client ID to filter by.
+     * @param null|integer $page      The page number, zero based.
+     * @param null|integer $per_page  The amount of entries per page.
+     *
+     * @return mixed
+     *
+     * @throws CoreException Thrown when $client_id is empty or not a string.
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/get_client_grants
+     */
+    public function getByClientId($client_id, $page = null, $per_page = null)
+    {
+        if (empty($client_id) || ! is_string($client_id)) {
+            throw new CoreException('Empty or invalid "client_id" parameter.');
+        }
+
+        return $this->getAll(['client_id' => $client_id], $page, $per_page);
+    }
+
+    /**
+     * Create a new Client Grant.
+     * Required scope: "create:client_grants"
+     *
+     * @param string $client_id Client ID to receive the grant.
+     * @param string $audience  Audience identifier for the API being granted.
+     * @param array  $scope     Array of scopes for the grant.
+     *
+     * @return mixed
+     *
+     * @throws CoreException Thrown when $client_id or $audience are empty or not a string.
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/post_client_grants
+     */
+    public function create($client_id, $audience, array $scope = [])
+    {
+        if (empty($client_id) || ! is_string($client_id)) {
+            throw new CoreException('Empty or invalid "client_id" parameter.');
+        }
+
+        if (empty($audience) || ! is_string($audience)) {
+            throw new CoreException('Empty or invalid "audience" parameter.');
+        }
+
+        return $this->apiClient->method('post')
+            ->addPath('client-grants')
+            ->withBody(json_encode([
+                'client_id' => $client_id,
+                'audience' => $audience,
+                'scope' => $scope,
+            ]))
+            ->call();
     }
 
     /**
+     * Delete a Client Grant by ID.
+     * Required scope: "delete:client_grants"
+     *
+     * @param string $id Client Grant ID to delete.
      *
-     * @param  string $client_id
-     * @param  string $audience
-     * @param  string $scope
      * @return mixed
+     *
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/delete_client_grants_by_id
      */
-    public function create($client_id, $audience, $scope)
+    public function delete($id)
     {
-        return $this->apiClient->post()
-        ->addPath('client-grants')
-        ->withHeader(new ContentType('application/json'))
-        ->withBody(json_encode([
-            'client_id' => $client_id,
-            'audience' => $audience,
-            'scope' => $scope,
-        ]))
-        ->call();
+        return $this->apiClient->method('delete')
+            ->addPath('client-grants', $id)
+            ->call();
     }
 
     /**
+     * Update an existing Client Grant.
+     * Required scope: "update:client_grants"
+     *
+     * @param string $id    Client Grant ID to update.
+     * @param array  $scope Array of scopes to update; will replace existing scopes, not merge.
      *
-     * @param  string      $id
-     * @param  null|string $audience
      * @return mixed
+     *
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Client_Grants/patch_client_grants_by_id
      */
-    public function delete($id, $audience = null)
+    public function update($id, array $scope)
     {
-        return $this->apiClient->delete()
-        ->addPath('client-grants', $id)
-        ->call();
+        return $this->apiClient->method('patch')
+            ->addPath('client-grants', $id)
+            ->withBody(json_encode(['scope' => $scope,]))
+            ->call();
     }
 
     /**
+     * Get a Client Grant.
+     * TODO: Deprecate, cannot get a Client Grant by ID.
+     *
+     * @param string      $id       Client Grant ID.
+     * @param null|string $audience Client Grant audience to filter by.
      *
-     * @param  string $id
-     * @param  string $scope
      * @return mixed
+     *
+     * @throws \Exception Thrown by the Guzzle HTTP client when there is a problem with the API call.
      */
-    public function update($id, $scope)
+    public function get($id, $audience = null)
     {
-        return $this->apiClient->patch()
-        ->addPath('client-grants', $id)
-        ->withHeader(new ContentType('application/json'))
-        ->withBody(json_encode([
-            'scope' => $scope,
-        ]))
-        ->call();
+        $request = $this->apiClient->get()
+            ->addPath('client-grants');
+
+        if ($audience !== null) {
+            $request = $request->withParam('audience', $audience);
+        }
+
+        return $request->call();
     }
 }

tests/API/ApiTests.php

@@ -2,11 +2,18 @@
 namespace Auth0\Tests\API;
 
 use Auth0\SDK\API\Helpers\TokenGenerator;
+use Auth0\SDK\API\Management;
 use josegonzalez\Dotenv\Loader;
 
 class ApiTests extends \PHPUnit_Framework_TestCase
 {
 
+    /**
+     *
+     * @var array
+     */
+    protected static $env = [];
+
     protected function getEnv()
     {
         return self::getEnvStatic();
@@ -46,4 +53,33 @@ protected static function getTokenStatic($env, $scopes)
         );
         return $generator->generate($scopes);
     }
+
+    /**
+     * Return an API client used during self::setUpBeforeClass().
+     *
+     * @param string $endpoint Endpoint name used for token generation.
+     * @param array  $actions  Actions required for token generation.
+     *
+     * @return mixed
+     */
+    protected static function getApiStatic($endpoint, array $actions)
+    {
+        self::$env  = self::getEnvStatic();
+        $token      = self::getTokenStatic(self::$env, [$endpoint => ['actions' => $actions]]);
+        $api_client = new Management($token, self::$env['DOMAIN']);
+        return $api_client->$endpoint;
+    }
+
+    /**
+     * Does an error message contain a specific string?
+     *
+     * @param \Exception $e   - Error object.
+     * @param string     $str - String to find in the error message.
+     *
+     * @return boolean
+     */
+    protected function errorHasString(\Exception $e, $str)
+    {
+        return ! (false === strpos($e->getMessage(), $str));
+    }
 }

tests/API/BasicCrudTest.php

@@ -12,13 +12,6 @@ abstract class BasicCrudTest extends ApiTests
      */
     protected $domain;
 
-    /**
-     * Environment variables, generated in self::__construct().
-     *
-     * @var array
-     */
-    protected $env;
-
     /**
      * API client to test.
      *
@@ -93,8 +86,8 @@ abstract protected function afterUpdate($updated_entity);
     public function __construct()
     {
         parent::__construct();
-        $this->env    = $this->getEnv();
-        $this->domain = $this->env['DOMAIN'];
+        self::$env    = $this->getEnv();
+        $this->domain = self::$env['DOMAIN'];
         $this->api    = $this->getApiClient();
         $this->rand   = rand();
     }
@@ -122,19 +115,6 @@ protected function getId($entity)
         return $entity[$this->id_name];
     }
 
-    /**
-     * Does an error message contain a specific string?
-     *
-     * @param \Exception $e   - Error object.
-     * @param string     $str - String to find in the error message.
-     *
-     * @return boolean
-     */
-    protected function errorHasString(\Exception $e, $str)
-    {
-        return ! (false === strpos($e->getMessage(), $str));
-    }
-
     /**
      * Check that HTTP options have been set correctly.
      */

tests/API/Management/AuthApiTest.php

@@ -59,7 +59,7 @@ public function testOauthToken()
 
         $token = $api->client_credentials(
             [
-                'audience' => 'tests'
+                'audience' => 'https://'.$env['DOMAIN'].'/api/v2/'
             ]
         );