From a6e096654b59251a37572bbf9b9f87ba03e00e0a Mon Sep 17 00:00:00 2001
From: Art4 <art4@wlabs.de>
Date: Tue, 10 Oct 2023 10:15:39 +0200
Subject: [PATCH] Add Role::list() method, deprecate all() method

---
 CHANGELOG.md                     |  2 +
 src/Redmine/Api/Role.php         | 22 +++++++++-
 tests/Unit/Api/Role/ListTest.php | 73 ++++++++++++++++++++++++++++++++
 tests/Unit/Api/RoleTest.php      | 27 ++++++++++++
 4 files changed, 122 insertions(+), 2 deletions(-)
 create mode 100644 tests/Unit/Api/Role/ListTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0c80c16d..053a5e90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
 
 ### Deprecated
 
@@ -35,6 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `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
 
 ## [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/Role.php b/src/Redmine/Api/Role.php
index 0250a9cf..63de7996 100644
--- a/src/Redmine/Api/Role.php
+++ b/src/Redmine/Api/Role.php
@@ -22,13 +22,31 @@ class Role extends AbstractApi
      *
      * @return array list of roles found
      */
-    public function all(array $params = [])
+    final public function list(array $params = []): array
     {
         $this->roles = $this->retrieveData('/roles.json', $params);
 
         return $this->roles;
     }
 
+    /**
+     * List roles.
+     *
+     * @deprecated since v2.4.0, use list() instead.
+     *
+     * @see http://www.redmine.org/projects/redmine/wiki/Rest_Roles#GET
+     *
+     * @param array $params optional parameters to be passed to the api (offset, limit, ...)
+     *
+     * @return array list of roles 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 roles with name/id pairs.
      *
@@ -39,7 +57,7 @@ public function all(array $params = [])
     public function listing($forceUpdate = false)
     {
         if (empty($this->roles) || $forceUpdate) {
-            $this->all();
+            $this->list();
         }
         $ret = [];
         foreach ($this->roles['roles'] as $e) {
diff --git a/tests/Unit/Api/Role/ListTest.php b/tests/Unit/Api/Role/ListTest.php
new file mode 100644
index 00000000..edd5effc
--- /dev/null
+++ b/tests/Unit/Api/Role/ListTest.php
@@ -0,0 +1,73 @@
+<?php
+
+namespace Redmine\Tests\Unit\Api\Role;
+
+use PHPUnit\Framework\TestCase;
+use Redmine\Api\Role;
+use Redmine\Client\Client;
+
+/**
+ * @covers \Redmine\Api\Role::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(
+                $this->stringStartsWith('/roles.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 Role($client);
+
+        // Perform the tests
+        $this->assertSame($expectedReturn, $api->list());
+    }
+
+    public function testListWithParametersReturnsResponse()
+    {
+        // Test values
+        $parameters = ['not-used'];
+        $response = '["API Response"]';
+        $expectedReturn = ['API Response'];
+
+        // Create the used mock objects
+        $client = $this->createMock(Client::class);
+        $client->expects($this->once())
+            ->method('requestGet')
+            ->with(
+                $this->logicalAnd(
+                    $this->stringStartsWith('/roles.json'),
+                    $this->stringContains('not-used')
+                )
+            )
+            ->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 Role($client);
+
+        // Perform the tests
+        $this->assertSame($expectedReturn, $api->list($parameters));
+    }
+}
diff --git a/tests/Unit/Api/RoleTest.php b/tests/Unit/Api/RoleTest.php
index 9d4ed9c0..61558ef7 100644
--- a/tests/Unit/Api/RoleTest.php
+++ b/tests/Unit/Api/RoleTest.php
@@ -5,6 +5,7 @@
 use PHPUnit\Framework\TestCase;
 use Redmine\Api\Role;
 use Redmine\Client\Client;
+use Redmine\Tests\Fixtures\MockClient;
 
 /**
  * @coversDefaultClass \Redmine\Api\Role
@@ -13,6 +14,32 @@
  */
 class RoleTest extends TestCase
 {
+    /**
+     * Test all().
+     *
+     * @covers ::all
+     */
+    public function testAllTriggersDeprecationWarning()
+    {
+        $api = new Role(MockClient::create());
+
+        // PHPUnit 10 compatible way to test trigger_error().
+        set_error_handler(
+            function ($errno, $errstr): bool {
+                $this->assertSame(
+                    '`Redmine\Api\Role::all()` is deprecated since v2.4.0, use `Redmine\Api\Role::list()` instead.',
+                    $errstr
+                );
+
+                restore_error_handler();
+                return true;
+            },
+            E_USER_DEPRECATED
+        );
+
+        $api->all();
+    }
+
     /**
      * Test all().
      *