[feat] Add paginated children (#328)

- Add `allChildren` and `getNextPageOfChildren` functions
- Add unit tests, cassettes

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next Release
+
+- Add `allChildren` and `getNextPageOfChildren` methods to `user` service
+
 ## v7.0.0 (2023-12-01)
 
 Upgrading major versions of this project? Refer to the [Upgrade Guide](UPGRADE_GUIDE.md).

lib/EasyPost/Service/UserService.php

@@ -2,6 +2,7 @@
 
 namespace EasyPost\Service;
 
+use EasyPost\Exception\General\EndOfPaginationException;
 use EasyPost\Http\Requestor;
 use EasyPost\Util\InternalUtil;
 
@@ -139,4 +140,60 @@ public function updateBrand(string $id, mixed $params = null): mixed
 
         return InternalUtil::convertToEasyPostObject($this->client, $response);
     }
+
+    /**
+     * Retrieve all child users.
+     *
+     * @param mixed $params
+     * @return mixed
+     */
+    public function allChildren(mixed $params = null): mixed
+    {
+        self::validate($params);
+
+        $url = '/users/children';
+        $response = Requestor::request($this->client, 'get', $url, $params);
+        if (isset($params)) {
+            $response['_params'] = $params;
+        }
+
+        return InternalUtil::convertToEasyPostObject($this->client, $response);
+    }
+
+    /**
+     * Retrieve the next page of child User collection
+     *
+     * @param mixed $children
+     * @param int|null $pageSize
+     * @return mixed
+     */
+    public function getNextPageOfChildren(mixed $children, ?int $pageSize = null): mixed
+    {
+        $userArray = $children['children'];
+        $userParams = $children['_params'] ?? null;
+
+        // Check to see if there is another page server-side before attempting to retrieve it
+        if (empty($userArray) || !$children['has_more']) {
+            throw new EndOfPaginationException();
+        }
+
+        $params = [
+            'page_size' => $pageSize,
+            'before_id' => $userArray[count($userArray) - 1]['id']
+        ];
+
+        if (isset($userParams)) {
+            $params = array_merge($params, $userParams);
+        }
+
+        // Retrieve a page of users from the server
+        $children = $this->allChildren($params);
+
+        // If the page we just retrieved is empty, then we have reached the end of the list
+        if (empty($children['children'])) {
+            throw new EndOfPaginationException();
+        }
+
+        return $children;
+    }
 }

test/EasyPost/UserTest.php

@@ -3,7 +3,9 @@
 namespace EasyPost\Test;
 
 use EasyPost\EasyPostClient;
+use EasyPost\Exception\General\EndOfPaginationException;
 use EasyPost\User;
+use Exception;
 
 class UserTest extends \PHPUnit\Framework\TestCase
 {
@@ -73,6 +75,52 @@ public function testRetrieveMe(): void
         $this->assertStringMatchesFormat('user_%s', $user->id);
     }
 
+    /**
+     * Test retrieving all child users.
+     */
+    public function testAllChildren(): void
+    {
+        TestUtil::setupCassette('users/allChildren.yml');
+
+        $children = self::$client->user->allChildren([
+            'page_size' => Fixture::pageSize(),
+        ]);
+
+        $userArray = $children['children'];
+
+        $this->assertLessThanOrEqual($userArray, Fixture::pageSize());
+        $this->assertNotNull($children['has_more']);
+        $this->assertContainsOnlyInstancesOf(User::class, $userArray);
+    }
+
+    /**
+     * Test retrieving next page.
+     * @noinspection RedundantSuppression
+     * @throws Exception
+     */
+    public function testGetNextPageOfChildren(): void
+    {
+        TestUtil::setupCassette('users/getNextPageOfChildren.yml');
+
+        try {
+            $children = self::$client->user->allChildren([
+                'page_size' => Fixture::pageSize(),
+            ]);
+            $nextPage = self::$client->user->getNextPageOfChildren($children, Fixture::pageSize());
+
+            $firstIdOfFirstPage = $children['children'][0]->id;
+            $secondIdOfSecondPage = $nextPage['children'][0]->id;
+
+            $this->assertNotEquals($firstIdOfFirstPage, $secondIdOfSecondPage);
+        } catch (EndOfPaginationException $error) {
+            // There's no second page, that's not a failure
+            $this->assertTrue(true);
+        } catch (Exception $error) {
+            /** @noinspection PhpExceptionImmediatelyRethrownInspection */
+            throw $error;
+        }
+    }
+
     /**
      * Test updating the authenticated user.
      */