Add list() methods and deprecate all() methods

.phpstan.neon

@@ -7,3 +7,5 @@ parameters:
 
     scanDirectories:
         - vendor
+
+    treatPhpDocTypesAsCertain: false

CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/kbsali/php-redmine-api/compare/v2.3.0...v2.x)
 
+### Added
+
+- New method `Redmine\Api\CustomField::list()` to list custom fields.
+- New method `Redmine\Api\Group::list()` to list groups.
+- New method `Redmine\Api\Issue::list()` to list issues.
+- New method `Redmine\Api\IssueCategory::listByProject()` to list issue categories from a project.
+- New method `Redmine\Api\IssuePriority::list()` to list issue priorities.
+- New method `Redmine\Api\IssueRelation::listByIssueId()` to list relations from an issue.
+- New method `Redmine\Api\IssueStatus::list()` to list issue statuses.
+- New method `Redmine\Api\Membership::listByProject()` to list memberships from a project.
+- New method `Redmine\Api\News::list()` to list news from all project.
+- New method `Redmine\Api\News::listByProject()` to list news from a project.
+- New method `Redmine\Api\Project::list()` to list projects.
+- New method `Redmine\Api\Query::list()` to list projects.
+- New method `Redmine\Api\Role::list()` to list roles.
+- New method `Redmine\Api\Search::listByQuery()` to list search results by query.
+- New method `Redmine\Api\TimeEntry::list()` to list time entries.
+- New method `Redmine\Api\TimeEntryActivity::list()` to list time entry activities.
+- New method `Redmine\Api\Tracker::list()` to list trackers.
+- New method `Redmine\Api\User::list()` to list users.
+- New method `Redmine\Api\Version::listByProject()` to list versions from a project.
+- New method `Redmine\Api\Wiki::listByProject()` to list wiki pages from a project.
+
+### Deprecated
+
+- `Redmine\Api\CustomField::all()` is deprecated, use `Redmine\Api\CustomField::list()` instead
+- `Redmine\Api\Group::all()` is deprecated, use `Redmine\Api\Group::list()` instead
+- `Redmine\Api\Issue::all()` is deprecated, use `Redmine\Api\Issue::list()` instead
+- `Redmine\Api\IssueCategory::all()` is deprecated, use `Redmine\Api\IssueCategory::listByProject()` instead
+- `Redmine\Api\IssuePriority::all()` is deprecated, use `Redmine\Api\IssuePriority::list()` instead
+- `Redmine\Api\IssueRelation::all()` is deprecated, use `Redmine\Api\IssueRelation::listByIssueId()` instead
+- `Redmine\Api\IssueStatus::all()` is deprecated, use `Redmine\Api\IssueStatus::list()` instead
+- `Redmine\Api\Membership::all()` is deprecated, use `Redmine\Api\Membership::listByProject()` instead
+- `Redmine\Api\News::all()` is deprecated, use `Redmine\Api\News::list()` or `Redmine\Api\News::listByProject()` instead
+- `Redmine\Api\Project::all()` is deprecated, use `Redmine\Api\Project::list()` instead
+- `Redmine\Api\Query::all()` is deprecated, use `Redmine\Api\Query::list()` instead
+- `Redmine\Api\Role::all()` is deprecated, use `Redmine\Api\Role::list()` instead
+- `Redmine\Api\Search::search()` is deprecated, use `Redmine\Api\Search::listByQuery()` instead
+- `Redmine\Api\TimeEntry::all()` is deprecated, use `Redmine\Api\TimeEntry::list()` instead
+- `Redmine\Api\TimeEntryActivity::all()` is deprecated, use `Redmine\Api\TimeEntryActivity::list()` instead
+- `Redmine\Api\Tracker::all()` is deprecated, use `Redmine\Api\Tracker::list()` instead
+- `Redmine\Api\User::all()` is deprecated, use `Redmine\Api\User::list()` instead
+- `Redmine\Api\Version::all()` is deprecated, use `Redmine\Api\Version::listByProject()` instead
+- `Redmine\Api\Wiki::all()` is deprecated, use `Redmine\Api\Wiki::listByProject()` instead
+
 ## [v2.3.0](https://github.com/kbsali/php-redmine-api/compare/v2.2.0...v2.3.0) - 2023-10-09
 
 ### Added

README.md

@@ -310,7 +310,7 @@ You can now use the `getApi()` method to create and get a specific Redmine API.
 ```php
 <?php
 
-$client->getApi('user')->all();
+$client->getApi('user')->list();
 $client->getApi('user')->listing();
 
 $client->getApi('issue')->create([
@@ -319,7 +319,7 @@ $client->getApi('issue')->create([
     'description' => 'a long description blablabla',
     'assigned_to_id' => 123, // or 'assigned_to' => 'user1' OR 'groupXX'
 ]);
-$client->getApi('issue')->all([
+$client->getApi('issue')->list([
     'limit' => 1000
 ]);
 ```

docs/usage.md

@@ -226,19 +226,19 @@ To check for failed requests you can afterwards check the status code via `$clie
 ```php
 // ----------------------------
 // Trackers
-$client->getApi('tracker')->all();
+$client->getApi('tracker')->list();
 $client->getApi('tracker')->listing();
 
 // ----------------------------
 // Issue statuses
-$client->getApi('issue_status')->all();
+$client->getApi('issue_status')->list();
 $client->getApi('issue_status')->listing();
 $client->getApi('issue_status')->getIdByName('New');
 
 // ----------------------------
 // Project
-$client->getApi('project')->all();
-$client->getApi('project')->all([
+$client->getApi('project')->list();
+$client->getApi('project')->list([
     'limit' => 10,
 ]);
 $client->getApi('project')->listing();
@@ -257,7 +257,7 @@ $client->getApi('project')->remove($projectId);
 
 // ----------------------------
 // Users
-$client->getApi('user')->all();
+$client->getApi('user')->list();
 $client->getApi('user')->listing();
 $client->getApi('user')->getCurrentUser([
     'include' => [
@@ -290,15 +290,15 @@ $client->getApi('user')->create([
 // ----------------------------
 // Issues
 $client->getApi('issue')->show($issueId);
-$client->getApi('issue')->all([
+$client->getApi('issue')->list([
     'limit' => 100,
 ]);
-$client->getApi('issue')->all(['category_id' => $categoryId]);
-$client->getApi('issue')->all(['tracker_id' => $trackerId]);
-$client->getApi('issue')->all(['status_id' => 'closed']);
-$client->getApi('issue')->all(['assigned_to_id' => $userId]);
-$client->getApi('issue')->all(['project_id' => 'test']);
-$client->getApi('issue')->all([
+$client->getApi('issue')->list(['category_id' => $categoryId]);
+$client->getApi('issue')->list(['tracker_id' => $trackerId]);
+$client->getApi('issue')->list(['status_id' => 'closed']);
+$client->getApi('issue')->list(['assigned_to_id' => $userId]);
+$client->getApi('issue')->list(['project_id' => 'test']);
+$client->getApi('issue')->list([
     'offset' => 100,
     'limit' => 100,
     'sort' => 'id',
@@ -375,7 +375,7 @@ $client->getApi('issue')->create([
 
 // ----------------------------
 // Issue categories
-$client->getApi('issue_category')->all('project1');
+$client->getApi('issue_category')->listByProject('project1');
 $client->getApi('issue_category')->listing($projectId);
 $client->getApi('issue_category')->show($categoryId);
 $client->getApi('issue_category')->getIdByName($projectId, 'Administration');
@@ -392,7 +392,7 @@ $client->getApi('issue_category')->remove($categoryId, [
 
 // ----------------------------
 // Versions
-$client->getApi('version')->all('test');
+$client->getApi('version')->listByProject('test');
 $client->getApi('version')->listing('test');
 $client->getApi('version')->show($versionId);
 $client->getApi('version')->getIdByName('test', 'v2');
@@ -413,24 +413,24 @@ file_put_contents('example.png', $file_content);
 
 // ----------------------------
 // News
-$client->getApi('news')->all('test');
-$client->getApi('news')->all();
+$client->getApi('news')->list();
+$client->getApi('news')->listByProject('test');
 
 // ----------------------------
 // Roles
-$client->getApi('role')->all();
+$client->getApi('role')->list();
 $client->getApi('role')->show(1);
 $client->getApi('role')->listing();
 
 // ----------------------------
 // Queries
-$client->getApi('query')->all();
+$client->getApi('query')->list();
 
 // ----------------------------
 // Time entries
-$client->getApi('time_entry')->all();
+$client->getApi('time_entry')->list();
 $client->getApi('time_entry')->show($timeEntryId);
-$client->getApi('time_entry')->all([
+$client->getApi('time_entry')->list([
     'issue_id' => 1234,
     'project_id' => 1234,
     'spent_on' => '2015-04-13',
@@ -470,17 +470,17 @@ $client->getApi('time_entry')->remove($timeEntryId);
 
 // ----------------------------
 // Time entry activities
-$client->getApi('time_entry_activity')->all();
+$client->getApi('time_entry_activity')->list();
 
 // ----------------------------
 // Issue relations
-$client->getApi('issue_relation')->all($issueId);
+$client->getApi('issue_relation')->listByIssueId($issueId);
 $client->getApi('issue_relation')->show($issueRelationId);
 $client->getApi('issue_relation')->remove($issueRelationId);
 
 // ----------------------------
 // Group (of members)
-$client->getApi('group')->all();
+$client->getApi('group')->list();
 $client->getApi('group')->listing();
 $client->getApi('group')->show($groupId, ['include' => 'users,memberships']);
 $client->getApi('group')->remove($groupId);
@@ -493,7 +493,7 @@ $client->getApi('group')->create([
 
 // ----------------------------
 // Project memberships
-$client->getApi('membership')->all($projectId);
+$client->getApi('membership')->listByProject($projectId);
 $client->getApi('membership')->create($projectId, [
     'user_id' => null,
     'role_ids' => [],
@@ -502,11 +502,11 @@ $client->getApi('membership')->remove($membershipId);
 
 // ----------------------------
 // Issue priorities
-$client->getApi('issue_priority')->all();
+$client->getApi('issue_priority')->list();
 
 // ----------------------------
 // Wiki
-$client->getApi('wiki')->all('testProject');
+$client->getApi('wiki')->listByProject('testProject');
 $client->getApi('wiki')->show('testProject', 'about');
 $client->getApi('wiki')->show('testProject', 'about', $version);
 $client->getApi('wiki')->create('testProject', 'about', [
@@ -523,19 +523,19 @@ $client->getApi('wiki')->remove('testProject', 'about');
 
 // ----------------------------
 // Issues' stats (see https://github.com/kbsali/php-redmine-api/issues/44)
-$issues['all'] = $client->getApi('issue')->all([
+$issues['all'] = $client->getApi('issue')->list([
     'limit' => 1,
     'tracker_id' => 1,
     'status_id' => '*',
 ])['total_count'];
 
-$issues['opened'] = $client->getApi('issue')->all([
+$issues['opened'] = $client->getApi('issue')->list([
     'limit' => 1,
     'tracker_id' => 1,
     'status_id' => 'open',
 ])['total_count'];
 
-$issues['closed'] = $client->getApi('issue')->all([
+$issues['closed'] = $client->getApi('issue')->list([
     'limit' => 1,
     'tracker_id' => 1,
     'status_id' => 'closed',

src/Redmine/Api/CustomField.php

@@ -22,13 +22,31 @@ class CustomField extends AbstractApi
      *
      * @return array list of custom fields found
      */
-    public function all(array $params = [])
+    final public function list(array $params = []): array
     {
         $this->customFields = $this->retrieveData('/custom_fields.json', $params);
 
         return $this->customFields;
     }
 
+    /**
+     * List custom fields.
+     *
+     * @deprecated since v2.4.0, use list() instead.
+     *
+     * @see http://www.redmine.org/projects/redmine/wiki/Rest_CustomFields#GET
+     *
+     * @param array $params optional parameters to be passed to the api (offset, limit, ...)
+     *
+     * @return array list of custom fields found
+     */
+    public function all(array $params = [])
+    {
+        @trigger_error('`'.__METHOD__.'()` is deprecated since v2.4.0, use `'.__CLASS__.'::list()` instead.', E_USER_DEPRECATED);
+
+        return $this->list($params);
+    }
+
     /**
      * Returns an array of custom fields with name/id pairs.
      *
@@ -40,7 +58,7 @@ public function all(array $params = [])
     public function listing($forceUpdate = false, array $params = [])
     {
         if (empty($this->customFields) || $forceUpdate) {
-            $this->all($params);
+            $this->list($params);
         }
         $ret = [];
         foreach ($this->customFields['custom_fields'] as $e) {

src/Redmine/Api/Group.php

@@ -27,13 +27,31 @@ class Group extends AbstractApi
      *
      * @return array list of groups found
      */
-    public function all(array $params = [])
+    final public function list(array $params = []): array
     {
         $this->groups = $this->retrieveData('/groups.json', $params);
 
         return $this->groups;
     }
 
+    /**
+     * List groups.
+     *
+     * @deprecated since v2.4.0, use list() instead.
+     *
+     * @see http://www.redmine.org/projects/redmine/wiki/Rest_Groups#GET
+     *
+     * @param array $params optional parameters to be passed to the api (offset, limit, ...)
+     *
+     * @return array list of groups found
+     */
+    public function all(array $params = [])
+    {
+        @trigger_error('`'.__METHOD__.'()` is deprecated since v2.4.0, use `'.__CLASS__.'::list()` instead.', E_USER_DEPRECATED);
+
+        return $this->list($params);
+    }
+
     /**
      * Returns an array of groups with name/id pairs.
      *
@@ -44,7 +62,7 @@ public function all(array $params = [])
     public function listing($forceUpdate = false)
     {
         if (empty($this->groups) || $forceUpdate) {
-            $this->all();
+            $this->list();
         }
         $ret = [];
         foreach ($this->groups['groups'] as $e) {

src/Redmine/Api/Issue.php

@@ -40,11 +40,39 @@ class Issue extends AbstractApi
      *
      * @return array list of issues found
      */
-    public function all(array $params = [])
+    final public function list(array $params = []): array
     {
         return $this->retrieveData('/issues.json', $params);
     }
 
+    /**
+     * List issues.
+     *
+     * @deprecated since v2.4.0, use list() instead.
+     *
+     * @see http://www.redmine.org/projects/redmine/wiki/Rest_Issues
+     * available $params :
+     * - offset: skip this number of issues in response (optional)
+     * - limit: number of issues per page (optional)
+     * - sort: column to sort with. Append :desc to invert the order.
+     * - project_id: get issues from the project with the given id, where id is either project id or project identifier
+     * - tracker_id: get issues from the tracker with the given id
+     * - status_id: get issues with the given status id only. Possible values: open, closed, * to get open and closed issues, status id
+     * - assigned_to_id: get issues which are assigned to the given user id
+     * - cf_x: get issues with the given value for custom field with an ID of x. (Custom field must have 'used as a filter' checked.)
+     * - query_id : id of the previously saved query
+     *
+     * @param array $params the additional parameters (cf available $params above)
+     *
+     * @return array list of issues found
+     */
+    public function all(array $params = [])
+    {
+        @trigger_error('`'.__METHOD__.'()` is deprecated since v2.4.0, use `'.__CLASS__.'::list()` instead.', E_USER_DEPRECATED);
+
+        return $this->list($params);
+    }
+
     /**
      * Get extended information about an issue gitven its id.
      *