Merge pull request #206 from helpscout/list-users-by-mailbox

Can now list users in a given mailbox

README.md

@@ -823,6 +823,18 @@ Get users.
 $users = $client->users()->list();
 ```
 
+Narrow down the list of Users based on a set of filters.
+
+```php
+use HelpScout\Api\Users\UserFilters;
+
+$filters = (new UserFilters())
+    ->withMailbox(1)
+    ->withEmail('[email protected]');
+
+$users = $client->users()->list($filters);
+```
+
 ## Reports
 
 When running reports using the SDK, refer to the [developer docs](https://developer.helpscout.com/mailbox-api/) for the exact endpoint, parameters, and response formats. While most of the endpoints in this SDK are little more than pass-through methods to call the API, there are a few conveniences.

examples/users.php

@@ -3,10 +3,17 @@
 require '_credentials.php';
 
 use HelpScout\Api\ApiClientFactory;
+use HelpScout\Api\Users\UserFilters;
 
 $client = ApiClientFactory::createClient();
 $client->useClientCredentials($appId, $appSecret);
 
+// List users
 $users = $client->users()->list();
 
+$filters = (new UserFilters())
+    ->withMailbox(197271);
+
+$users = $client->users()->list($filters);
+
 print_r($users->getFirstPage()->toArray());

src/Users/UserFilters.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HelpScout\Api\Users;
+
+use HelpScout\Api\Assert\Assert;
+
+class UserFilters
+{
+    /**
+     * @var int
+     */
+    private $mailbox;
+
+    /**
+     * @var string
+     */
+    private $email;
+
+    public function getParams(): array
+    {
+        $params = [
+            'mailbox' => $this->mailbox,
+            'email' => $this->email,
+        ];
+
+        // Filter out null values & empty strings
+        return array_filter($params);
+    }
+
+    /**
+     * @return self
+     */
+    public function withMailbox(int $mailbox)
+    {
+        Assert::greaterThan($mailbox, 0);
+
+        $filters = clone $this;
+        $filters->mailbox = $mailbox;
+
+        return $filters;
+    }
+
+    /**
+     * @return self
+     */
+    public function withEmail(string $email)
+    {
+        $filters = clone $this;
+        $filters->email = $email;
+
+        return $filters;
+    }
+}

src/Users/UsersEndpoint.php

@@ -33,12 +33,21 @@ public function getAuthenticatedUser(): User
     /**
      * @return User[]|PagedCollection
      */
-    public function list(): PagedCollection
-    {
+    public function list(
+        UserFilters $userFilters = null
+    ): PagedCollection {
+        $uri = self::LIST_USERS_URI;
+        if ($userFilters) {
+            $params = $userFilters->getParams();
+            if (!empty($params)) {
+                $uri .= '?'.http_build_query($params);
+            }
+        }
+
         return $this->loadPage(
             User::class,
             self::RESOURCE_KEY,
-            self::LIST_USERS_URI
+            $uri
         );
     }
 }

tests/Users/UserClientIntegrationTest.php

@@ -7,6 +7,7 @@
 use HelpScout\Api\Tests\ApiClientIntegrationTestCase;
 use HelpScout\Api\Tests\Payloads\UserPayloads;
 use HelpScout\Api\Users\User;
+use HelpScout\Api\Users\UserFilters;
 
 /**
  * @group integration
@@ -108,4 +109,23 @@ public function testGetUsersLazyLoadsPages()
             ['GET', 'https://api.helpscout.net/v2/users?page=2'],
         ]);
     }
+
+    public function testListUsersWithFilters()
+    {
+        $this->stubResponse(
+            $this->getResponse(200, UserPayloads::getUsers(1, 10))
+        );
+
+        $filters = (new UserFilters())
+            ->withMailbox(256);
+
+        $users = $this->client->users()->list($filters);
+
+        $this->assertCount(10, $users);
+        $this->assertInstanceOf(User::class, $users[0]);
+
+        $this->verifySingleRequest(
+            'https://api.helpscout.net/v2/users?mailbox=256'
+        );
+    }
 }

tests/Users/UserFiltersTest.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HelpScout\Api\Tests\Users;
+
+use HelpScout\Api\Users\UserFilters;
+use PHPUnit\Framework\TestCase;
+
+class UserFiltersTest extends TestCase
+{
+    public function testGetParamsDoesNotReturnNullValues()
+    {
+        $filters = new UserFilters();
+
+        $this->assertSame([], $filters->getParams());
+    }
+
+    public function testGetParams()
+    {
+        $filters = (new UserFilters())
+            ->withMailbox(1)
+            ->withEmail('[email protected]');
+
+        $this->assertSame([
+            'mailbox' => 1,
+            'email' => '[email protected]',
+        ], $filters->getParams());
+    }
+}