From 1bcaf883a9b7efd87cc231ec3714496ecf6ca84c Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Tue, 10 Oct 2023 16:12:08 +0200
Subject: [PATCH] Add User::list() method, deprecated all() method

---
 CHANGELOG.md                     |  2 +
 src/Redmine/Api/User.php         | 20 ++++++++-
 tests/Unit/Api/User/ListTest.php | 69 ++++++++++++++++++++++++++++++++
 tests/Unit/Api/UserTest.php      | 27 +++++++++++++
 4 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 tests/Unit/Api/User/ListTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6db298dd..86e952c2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
 
 ### Deprecated
 
@@ -45,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `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
 
 ## [v2.3.0](https://github.com/kbsali/php-redmine-api/compare/v2.2.0...v2.3.0) - 2023-10-09
 
diff --git a/src/Redmine/Api/User.php b/src/Redmine/Api/User.php
index 05c4fc09..7b0151f2 100644
--- a/src/Redmine/Api/User.php
+++ b/src/Redmine/Api/User.php
@@ -26,13 +26,31 @@ class User extends AbstractApi
      *
      * @return array list of users found
      */
-    public function all(array $params = [])
+    final public function list(array $params = []): array
     {
         $this->users = $this->retrieveData('/users.json', $params);
 
         return $this->users;
     }
 
+    /**
+     * List users.
+     *
+     * @deprecated since v2.4.0, use list() instead.
+     *
+     * @see http://www.redmine.org/projects/redmine/wiki/Rest_Users#GET
+     *
+     * @param array $params to allow offset/limit (and more) to be passed
+     *
+     * @return array list of users 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 users with login/id pairs.
      *
diff --git a/tests/Unit/Api/User/ListTest.php b/tests/Unit/Api/User/ListTest.php
new file mode 100644
index 00000000..82c554a2
--- /dev/null
+++ b/tests/Unit/Api/User/ListTest.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace Redmine\Tests\Unit\Api\User;
+
+use PHPUnit\Framework\TestCase;
+use Redmine\Api\User;
+use Redmine\Client\Client;
+
+/**
+ * @covers \Redmine\Api\User::list
+ */
+class ListTest extends TestCase
+{
+    public function testListWithoutParametersReturnsResponse()
+    {
+        // Test values
+        $response = '["API Response"]';
+        $expectedReturn = ['API Response'];
+
+        // Create the used mock objects
+        $client = $this->createMock(Client::class);
+        $client->expects($this->once())
+            ->method('requestGet')
+            ->with('/users.json')
+            ->willReturn(true);
+        $client->expects($this->exactly(1))
+            ->method('getLastResponseBody')
+            ->willReturn($response);
+        $client->expects($this->exactly(1))
+            ->method('getLastResponseContentType')
+            ->willReturn('application/json');
+
+        // Create the object under test
+        $api = new User($client);
+
+        // Perform the tests
+        $this->assertSame($expectedReturn, $api->list());
+    }
+
+    public function testListWithParametersReturnsResponse()
+    {
+        // Test values
+        $parameters = [
+            'offset' => 10,
+            'limit' => 2,
+        ];
+        $response = '["API Response"]';
+        $expectedReturn = ['API Response'];
+
+        // Create the used mock objects
+        $client = $this->createMock(Client::class);
+        $client->expects($this->once())
+            ->method('requestGet')
+            ->with('/users.json?limit=2&offset=10')
+            ->willReturn(true);
+        $client->expects($this->exactly(1))
+            ->method('getLastResponseBody')
+            ->willReturn($response);
+        $client->expects($this->exactly(1))
+            ->method('getLastResponseContentType')
+            ->willReturn('application/json');
+
+        // Create the object under test
+        $api = new User($client);
+
+        // Perform the tests
+        $this->assertSame($expectedReturn, $api->list($parameters));
+    }
+}
diff --git a/tests/Unit/Api/UserTest.php b/tests/Unit/Api/UserTest.php
index e3746fcc..9d1d7087 100644
--- a/tests/Unit/Api/UserTest.php
+++ b/tests/Unit/Api/UserTest.php
@@ -6,6 +6,7 @@
 use Redmine\Api\User;
 use Redmine\Client\Client;
 use Redmine\Exception\MissingParameterException;
+use Redmine\Tests\Fixtures\MockClient;
 
 /**
  * @coversDefaultClass \Redmine\Api\User
@@ -88,6 +89,32 @@ public function testGetIdByUsernameMakesGetRequest()
         $this->assertSame(5, $api->getIdByUsername('User 5'));
     }
 
+    /**
+     * Test all().
+     *
+     * @covers ::all
+     */
+    public function testAllTriggersDeprecationWarning()
+    {
+        $api = new User(MockClient::create());
+
+        // PHPUnit 10 compatible way to test trigger_error().
+        set_error_handler(
+            function ($errno, $errstr): bool {
+                $this->assertSame(
+                    '`Redmine\Api\User::all()` is deprecated since v2.4.0, use `Redmine\Api\User::list()` instead.',
+                    $errstr
+                );
+
+                restore_error_handler();
+                return true;
+            },
+            E_USER_DEPRECATED
+        );
+
+        $api->all();
+    }
+
     /**
      * Test all().
      *