diff --git a/README.md b/README.md index 2319d382..bfb30c8a 100644 --- a/README.md +++ b/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('tester@test.com'); + +$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. diff --git a/examples/users.php b/examples/users.php index 8143e04e..f54a1734 100644 --- a/examples/users.php +++ b/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()); diff --git a/src/Users/UserFilters.php b/src/Users/UserFilters.php new file mode 100644 index 00000000..22741ed7 --- /dev/null +++ b/src/Users/UserFilters.php @@ -0,0 +1,55 @@ + $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; + } +} diff --git a/src/Users/UsersEndpoint.php b/src/Users/UsersEndpoint.php index 298af6d0..2ab76aec 100644 --- a/src/Users/UsersEndpoint.php +++ b/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 ); } } diff --git a/tests/Users/UserClientIntegrationTest.php b/tests/Users/UserClientIntegrationTest.php index 98498c7e..af6d89cb 100644 --- a/tests/Users/UserClientIntegrationTest.php +++ b/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' + ); + } } diff --git a/tests/Users/UserFiltersTest.php b/tests/Users/UserFiltersTest.php new file mode 100644 index 00000000..235b054f --- /dev/null +++ b/tests/Users/UserFiltersTest.php @@ -0,0 +1,30 @@ +assertSame([], $filters->getParams()); + } + + public function testGetParams() + { + $filters = (new UserFilters()) + ->withMailbox(1) + ->withEmail('tester@test.com'); + + $this->assertSame([ + 'mailbox' => 1, + 'email' => 'tester@test.com', + ], $filters->getParams()); + } +}