Merge pull request #224 from fbourigault/options-resolver

Use options resolver almost everywhere

UPGRADE.md

@@ -13,15 +13,32 @@ See [documentation](doc/customize.md) to know how to customize the client timeou
 * The `setHttpClient` method have been removed. Use a `Gitlab\HttpClient\Builder` instead. 
 * The `getHttpClient` method return type is changed to `Http\Client\Common\HttpMethodsClient`.
 
+## `Gitlab\Api\AbstractApi` changes
+
+* The `PER_PAGE` class constant have been removed.
+
+## `Gitlab\Api\DeployKeys` changes
+
+* The `all` method now take a single argument which is an associative array of query string parameters.
+* The `ORDER_BY` and `SORT` class constants have been removed.
 
 ## `Gitlab\Api\Groups` changes
 
 * The `visibility_level` parameter have been removed from `create` method. Use `visibility` instead.
+* The `all` method now take a single argument which is an associative array of query string parameters.
+* The `search` method have been removed. Use `all` method instead.
+* The `members` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+* The `projects` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
 
 ## `Gitlab\Api\Issues` changes
 
 * The second argument of `update`, `remove`, `showComments`, `showComment`, `addComment`, `updateComment`, `removeComment`,
  `setTimeEstimate`, `resetTimeEstimate`, `addSpentTime` and `resetSpentTime` methods is now a scoped issue id (iid).
+* The `all` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+
+## `Gitlab\Api\IssueBoards` changes
+
+* The `all` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
 
 ## `Gitlab\Api\MergeRequests` changes
 
@@ -30,6 +47,10 @@ See [documentation](doc/customize.md) to know how to customize the client timeou
 * The `all` method now take a single argument which is an associative array of query string parameters.
 * The `getNotes` method now take only two arguments, the project id and the merge request iid.
 
+## `Gitlab\Api\Milestones` changes
+
+* The `all` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+
 ## `Gitlab\Api\Projects` changes
 
 * The `keys`, `key`, `addKey`, `removeKey`, `disableKey` and `enableKey` methods have been removed.
@@ -40,11 +61,19 @@ Use the `deployKeys`, `deployKey`, `addDeployKey`, `deleteDeployKey`, `removeDep
 * The `trace` method have been removed. Use `Gitlab\Api\Jobs::trace` instead.
 * The `builds` method have been removed. Use `Gitlab\Api\Jobs::all` instead.
 * The `build` method have been removed. Use `Gitlab\Api\Jobs::show` instead.
+* The `events` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+* The `deployments` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+
+## `Gitlab\Api\ProjectNamespaces` changes
+
+* The `search` method have been removed. Use `all` method instead.
+* The `all` method now take a single argument which is an associative array of query string parameters.
 
 ## `Gitlab\Api\Repositories` changes
 
-* The `commits` page argument now start from 1 instead of 0.
 * The `commitBuilds` method have been removed. Use `Gitlab\Api\Projects::pipelines` instead.
+* The `commits` method second and subsequent arguments have been replaced by a single associative array of query string parameters.
+* The `commitComments` method third and subsequent arguments have been replaced by a single associative array of query string parameters.
 
 ## `Gitlab\Model\Project` changes
 
@@ -53,4 +82,9 @@ Use the `deployKeys`, `deployKey`, `addDeployKey`, `deleteDeployKey`, `removeDep
 
 ## `Gitlab\Model\Snippet` changes
 
-The `expires_at` property have been removed.`
+* The `expires_at` property have been removed.`
+
+## `Gitlab\Model\Users` changes
+
+* The `all` method now take a single argument which is an associative array of query string parameters.
+* The `lookup` and `search` methods have been removed. Use `all` method instead.

lib/Gitlab/Api/AbstractApi.php

@@ -19,11 +19,6 @@
  */
 abstract class AbstractApi implements ApiInterface
 {
-    /**
-     * Default entries per page
-     */
-    const PER_PAGE = 20;
-
     /**
      * The client
      *
@@ -179,7 +174,7 @@ protected function encodePath($path)
     }
 
     /**
-     * Create a new OptionsResolver with page, per_page and sort options.
+     * Create a new OptionsResolver with page and per_page options.
      *
      * @return OptionsResolver
      */
@@ -198,9 +193,6 @@ protected function createOptionsResolver()
                 return $value > 0 && $value <= 100;
             })
         ;
-        $resolver->setDefined('sort')
-            ->setAllowedValues('sort', ['asc', 'desc'])
-        ;
 
         return $resolver;
     }

lib/Gitlab/Api/DeployKeys.php

@@ -2,23 +2,15 @@
 
 class DeployKeys extends AbstractApi
 {
-    const ORDER_BY = 'id';
-    const SORT = 'asc';
-
     /**
-     * @param int $page
-     * @param int $per_page
-     * @param string $order_by
-     * @param string $sort
+     * @param array $parameters
+     *
      * @return mixed
      */
-    public function all($page = 1, $per_page = self::PER_PAGE, $order_by = self::ORDER_BY, $sort = self::SORT)
+    public function all(array $parameters = [])
     {
-        return $this->get('deploy_keys', array(
-            'page' => $page,
-            'per_page' => $per_page,
-            'order_by' => $order_by,
-            'sort' => $sort
-        ));
+        $resolver = $this->createOptionsResolver();
+
+        return $this->get('deploy_keys', $resolver->resolve($parameters));
     }
 }

lib/Gitlab/Api/Groups.php

@@ -3,30 +3,52 @@
 class Groups extends AbstractApi
 {
     /**
-     * @param int $page
-     * @param int $per_page
+     * @param array $parameters (
+     *
+     *     @var int[]  $skip_groups   Skip the group IDs passes.
+     *     @var bool   $all_available Show all the groups you have access to.
+     *     @var string $search        Return list of authorized groups matching the search criteria.
+     *     @var string $order_by      Order groups by name or path. Default is name.
+     *     @var string $sort          Order groups in asc or desc order. Default is asc.
+     *     @var bool   $statistics    Include group statistics (admins only).
+     *     @var bool   $owned         Limit by groups owned by the current user.
+     * )
      * @return mixed
      */
-    public function all($page = 1, $per_page = self::PER_PAGE)
+    public function all(array $parameters = [])
     {
-        return $this->get('groups', array(
-            'page' => $page,
-            'per_page' => $per_page
-        ));
-    }
+        $resolver = $this->createOptionsResolver();
+        $booleanNormalizer = function ($value) {
+            return $value ? 'true' : 'false';
+        };
 
-    /**
-     * @param string $query
-     * @param int $page
-     * @param int $per_page
-     * @return mixed
-     */
-    public function search($query, $page = 1, $per_page = self::PER_PAGE)
-    {
-        return $this->get('groups?search='.$this->encodePath($query), array(
-            'page' => $page,
-            'per_page' => $per_page
-        ));
+        $resolver->setDefined('skip_groups')
+            ->setAllowedTypes('skip_groups', 'array')
+            ->setAllowedValues('skip_groups', function (array $value) {
+                return count($value) == count(array_filter($value, 'is_int'));
+            })
+        ;
+        $resolver->setDefined('all_available')
+            ->setAllowedTypes('all_available', 'bool')
+            ->setNormalizer('all_available', $booleanNormalizer)
+        ;
+        $resolver->setDefined('search');
+        $resolver->setDefined('order_by')
+            ->setAllowedValues('order_by', ['name', 'path'])
+        ;
+        $resolver->setDefined('sort')
+            ->setAllowedValues('sort', ['asc', 'desc'])
+        ;
+        $resolver->setDefined('statistics')
+            ->setAllowedTypes('statistics', 'bool')
+            ->setNormalizer('statistics', $booleanNormalizer)
+        ;
+        $resolver->setDefined('owned')
+            ->setAllowedTypes('owned', 'bool')
+            ->setNormalizer('owned', $booleanNormalizer)
+        ;
+
+        return $this->get('groups', $resolver->resolve($parameters));
     }
 
     /**
@@ -85,17 +107,20 @@ public function transfer($group_id, $project_id)
     }
 
     /**
-     * @param int $id
-     * @param int $page
-     * @param int $per_page
+     * @param int   $id
+     * @param array $parameters (
+     *
+     *     @var string $query A query string to search for members.
+     * )
+     *
      * @return mixed
      */
-    public function members($id, $page = 1, $per_page = self::PER_PAGE)
+    public function members($id, array $parameters = [])
     {
-        return $this->get('groups/'.$this->encodePath($id).'/members', array(
-            'page' => $page,
-            'per_page' => $per_page
-        ));
+        $resolver = $this->createOptionsResolver();
+        $resolver->setDefined('query');
+
+        return $this->get('groups/'.$this->encodePath($id).'/members', $resolver->resolve($parameters));
     }
 
     /**
@@ -137,15 +162,55 @@ public function removeMember($group_id, $user_id)
 
     /**
      * @param $id
-     * @param int $page
-     * @param int $per_page
+     * @param array $parameters (
+     *
+     *     @var bool   $archived   Limit by archived status.
+     *     @var string $visibility Limit by visibility public, internal, or private.
+     *     @var string $order_by   Return projects ordered by id, name, path, created_at, updated_at, or last_activity_at fields.
+     *                             Default is created_at.
+     *     @var string $sort       Return projects sorted in asc or desc order. Default is desc.
+     *     @var string $search     Return list of authorized projects matching the search criteria.
+     *     @var bool   $simple     Return only the ID, URL, name, and path of each project.
+     *     @var bool   $owned      Limit by projects owned by the current user.
+     *     @var bool   $starred    Limit by projects starred by the current user.
+     * )
+     *
      * @return mixed
      */
-    public function projects($id, $page = 1, $per_page = self::PER_PAGE)
+    public function projects($id, array $parameters = [])
     {
-        return $this->get('groups/'.$this->encodePath($id).'/projects', array(
-            'page' => $page,
-            'per_page' => $per_page
-        ));
+        $resolver = $this->createOptionsResolver();
+        $booleanNormalizer = function ($value) {
+            return $value ? 'true' : 'false';
+        };
+
+        $resolver->setDefined('archived')
+            ->setAllowedTypes('archived', 'bool')
+            ->setNormalizer('archived', $booleanNormalizer)
+        ;
+        $resolver->setDefined('visibility')
+            ->setAllowedValues('visibility', ['public', 'internal', 'private'])
+        ;
+        $resolver->setDefined('order_by')
+            ->setAllowedValues('order_by', ['id', 'name', 'path', 'created_at', 'updated_at', 'last_activity_at'])
+        ;
+        $resolver->setDefined('sort')
+            ->setAllowedValues('sort', ['asc', 'desc'])
+        ;
+        $resolver->setDefined('search');
+        $resolver->setDefined('simple')
+            ->setAllowedTypes('simple', 'bool')
+            ->setNormalizer('simple', $booleanNormalizer)
+        ;
+        $resolver->setDefined('owned')
+            ->setAllowedTypes('owned', 'bool')
+            ->setNormalizer('owned', $booleanNormalizer)
+        ;
+        $resolver->setDefined('starred')
+            ->setAllowedTypes('starred', 'bool')
+            ->setNormalizer('starred', $booleanNormalizer)
+        ;
+
+        return $this->get('groups/'.$this->encodePath($id).'/projects', $resolver->resolve($parameters));
     }
 }

lib/Gitlab/Api/IssueBoards.php

@@ -4,21 +4,17 @@ class IssueBoards extends AbstractApi
 {
     /**
      * @param int $project_id
-     * @param int $page
-     * @param int $per_page
-     * @param array $params
+     * @param array $parameters
+     *
      * @return mixed
      */
-    public function all($project_id = null, $page = 1, $per_page = self::PER_PAGE, array $params = array())
+    public function all($project_id = null, array $parameters = [])
     {
-        $path = $project_id === null ? 'boards' : $this->getProjectPath($project_id, 'boards');
+        $resolver = $this->createOptionsResolver();
 
-        $params = array_merge(array(
-            'page' => $page,
-            'per_page' => $per_page
-        ), $params);
+        $path = $project_id === null ? 'boards' : $this->getProjectPath($project_id, 'boards');
 
-        return $this->get($path, $params);
+        return $this->get($path, $resolver->resolve($parameters));
     }
 
     /**

lib/Gitlab/Api/Issues.php

@@ -4,22 +4,46 @@ class Issues extends AbstractApi
 {
     /**
      * @param int $project_id
-     * @param int $page
-     * @param int $per_page
-     * @param array $params
+     * @param array $parameters (
+     *
+     *     @var string $state     Return all issues or just those that are opened or closed.
+     *     @var string $labels    Comma-separated list of label names, issues must have all labels to be returned.
+     *                            No+Label lists all issues with no labels.
+     *     @var string $milestone The milestone title.
+     *     @var int[]  $iids      Return only the issues having the given iid.
+     *     @var string $order_by  Return requests ordered by created_at or updated_at fields. Default is created_at.
+     *     @var string $sort      Return requests sorted in asc or desc order. Default is desc.
+     *     @var string $search    Search issues against their title and description.
+     * )
+     *
      * @return mixed
      */
-    public function all($project_id = null, $page = 1, $per_page = self::PER_PAGE, array $params = array())
+    public function all($project_id = null, array $parameters = [])
     {
-        $path = $project_id === null ? 'issues' : $this->getProjectPath($project_id, 'issues');
+        $resolver = $this->createOptionsResolver();
+
+        $resolver->setDefined('state')
+            ->setAllowedValues('state', ['opened', 'closed'])
+        ;
+        $resolver->setDefined('labels');
+        $resolver->setDefined('milestone');
+        $resolver->setDefined('iids')
+            ->setAllowedTypes('iids', 'array')
+            ->setAllowedValues('iids', function (array $value) {
+                return count($value) == count(array_filter($value, 'is_int'));
+            })
+        ;
+        $resolver->setDefined('order_by')
+            ->setAllowedValues('order_by', ['created_at', 'updated_at'])
+        ;
+        $resolver->setDefined('sort')
+            ->setAllowedValues('sort', ['asc', 'desc'])
+        ;
+        $resolver->setDefined('search');
 
-        $params = array_intersect_key($params, array('labels' => '', 'state' => '', 'sort' => '', 'order_by' => '', 'milestone' => ''));
-        $params = array_merge(array(
-            'page' => $page,
-            'per_page' => $per_page
-        ), $params);
+        $path = $project_id === null ? 'issues' : $this->getProjectPath($project_id, 'issues');
 
-        return $this->get($path, $params);
+        return $this->get($path, $resolver->resolve($parameters));
     }
 
     /**