Add pagination, docs, and better tests for Rules

src/API/Management/Rules.php

@@ -2,107 +2,175 @@
 
 namespace Auth0\SDK\API\Management;
 
-use Auth0\SDK\API\Header\ContentType;
-
+use Auth0\SDK\Exception\CoreException;
+
+/**
+ * Class Rules.
+ * Handles requests to the Rules endpoint of the v2 Management API.
+ *
+ * @package Auth0\SDK\API\Management
+ */
 class Rules extends GenericResource
 {
     /**
+     * Get all Rules, by page if desired.
+     * Required scope: "read:rules"
+     *
+     * @param null|boolean      $enabled        Retrieves rules that match the value, otherwise all rules are retrieved.
+     * @param null|string|array $fields         Fields to include or exclude from the result.
+     * @param null|boolean      $include_fields True to include $fields, false to exclude $fields.
+     * @param null|integer      $page           Page number to get, zero-based.
+     * @param null|integer      $per_page       Number of results to get, null to return the default number.
      *
-     * @param  null|string       $enabled
-     * @param  null|string|array $fields
-     * @param  null|string|array $include_fields
      * @return mixed
+     *
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Rules/get_rules
      */
-    public function getAll($enabled = null, $fields = null, $include_fields = null)
+    public function getAll($enabled = null, $fields = null, $include_fields = null, $page = null, $per_page = null)
     {
-        $request = $this->apiClient->get()
-            ->rules();
+        $params = [];
 
+        // Only return enabled Rules.
         if ($enabled !== null) {
-            $request->withParam('enabled', $enabled);
+            $params['enabled'] = (bool) $enabled;
         }
 
-        if ($fields !== null) {
-            if (is_array($fields)) {
-                $fields = implode(',', $fields);
+        // Fields to include or exclude from results.
+        if (! empty($fields)) {
+            $params['fields'] = is_array($fields) ? implode(',', $fields) : $fields;
+            if (null !== $include_fields) {
+                $params['include_fields'] = $include_fields;
             }
+        }
 
-            $request->withParam('fields', $fields);
+        // Pagination parameters.
+        if (null !== $page) {
+            $params['page'] = abs(intval($page));
         }
 
-        if ($include_fields !== null) {
-            $request->withParam('include_fields', $include_fields);
+        if (null !== $per_page) {
+            $params['per_page'] = abs(intval($per_page));
         }
 
-        return $request->call();
+        return $this->apiClient->method('get')
+            ->addPath('rules')
+            ->withDictParams($params)
+            ->call();
     }
 
     /**
+     * Get a single rule by ID.
+     * Required scope: "read:rules"
+     *
+     * @param string            $id             Rule ID to get.
+     * @param null|string|array $fields         Fields to include or exclude from the result.
+     * @param null|boolean      $include_fields True to include $fields, false to exclude $fields.
      *
-     * @param  string            $id
-     * @param  null|string|array $fields
-     * @param  null|string|array $include_fields
      * @return mixed
+     *
+     * @throws CoreException Thrown when $id is empty or not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Rules/get_rules_by_id
      */
     public function get($id, $fields = null, $include_fields = null)
     {
-        $request = $this->apiClient->get()
-            ->rules($id);
-
-        if ($fields !== null) {
-            if (is_array($fields)) {
-                $fields = implode(',', $fields);
-            }
-
-            $request->withParam('fields', $fields);
+        if (empty($id) || ! is_string($id)) {
+            throw new CoreException('Invalid "id" parameter.');
         }
 
-        if ($include_fields !== null) {
-            $request->withParam('include_fields', $include_fields);
-        }
+        $params = [];
 
-        $info = $request->call();
+        // Fields to include or exclude from results.
+        if (! empty($fields)) {
+            $params['fields'] = is_array($fields) ? implode(',', $fields) : $fields;
+            if (null !== $include_fields) {
+                $params['include_fields'] = $include_fields;
+            }
+        }
 
-        return $info;
+        return $this->apiClient->method('get')
+            ->addPath('rules', $id)
+            ->withDictParams($params)
+            ->call();
     }
 
     /**
+     * Delete a rule by ID.
+     * Required scope: "delete:rules"
+     *
+     * @param string $id Rule ID to delete.
      *
-     * @param  string $id
      * @return mixed
+     *
+     * @throws CoreException Thrown when $id is empty or not a string.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Rules/delete_rules_by_id
      */
     public function delete($id)
     {
-        return $this->apiClient->delete()
-            ->rules($id)
+        if (empty($id) || ! is_string($id)) {
+            throw new CoreException('Invalid "id" parameter.');
+        }
+
+        return $this->apiClient->method('delete')
+            ->addPath('rules', $id)
             ->call();
     }
 
     /**
+     * Create a new Rule.
+     * Required scope: "create:rules"
+     *
+     * @param array $data Dictionary array of keys and values to create a Rule.
      *
-     * @param  array $data
      * @return mixed
+     *
+     * @throws CoreException Thrown when required "script" or "name" fields are missing or empty.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
+     *
+     * @link https://auth0.com/docs/api/management/v2#!/Rules/post_rules
+     * @link https://auth0.com/docs/rules/current#create-rules-with-the-management-api
      */
-    public function create($data)
+    public function create(array $data)
     {
-        return $this->apiClient->post()
-            ->rules()
-            ->withHeader(new ContentType('application/json'))
+        if (empty($data['name'])) {
+            throw new CoreException('Missing required "name" field.');
+        }
+
+        if (empty($data['script'])) {
+            throw new CoreException('Missing required "script" field.');
+        }
+
+        return $this->apiClient->method('post')
+            ->addPath('rules')
             ->withBody(json_encode($data))
             ->call();
     }
 
     /**
+     * Update a Rule by ID.
+     * Required scope: "update:rules"
+     *
+     * @param string $id   Rule ID to delete.
+     * @param array  $data Rule data to update.
      *
-     * @param  string $id
-     * @param  array  $data
      * @return mixed
+     *
+     * @throws CoreException Thrown when $id is empty or not a string or if $data is empty.
+     * @throws \Exception Thrown by the HTTP client when there is a problem with the API call.
      */
-    public function update($id, $data)
+    public function update($id, array $data)
     {
-        return $this->apiClient->patch()
-            ->rules($id)
-            ->withHeader(new ContentType('application/json'))
+        if (empty($id) || ! is_string($id)) {
+            throw new CoreException('Invalid "id" parameter.');
+        }
+
+        return $this->apiClient->method('patch')
+            ->addPath('rules', $id)
             ->withBody(json_encode($data))
             ->call();
     }

tests/API/Management/ClientGrantsTest.php

@@ -102,7 +102,7 @@ public function testGetWithPagination()
      */
     public function testGetAllIncludeTotals()
     {
-        $expected_page  = 1;
+        $expected_page  = 0;
         $expected_count = 2;
 
         $results = self::$api->getAll(['include_totals' => true], $expected_page, $expected_count);