class PagedListResponse implements IteratorAggregate (View source)

Response object for paged results from a list API method

The PagedListResponse object is returned by API methods that implement pagination, and makes it easier to access multiple pages of results without having to manually manipulate page tokens. Pages are retrieved lazily, with additional API calls being made as additional results are required.

The list elements can be accessed in the following ways:

  • As a single iterable used in a foreach loop or via the getIterator method
  • As pages of elements, using the getPage and iteratePages methods
  • As fixed size collections of elements, using the getFixedSizeCollection and iterateFixedSizeCollections methods

Example of using PagedListResponse as an iterator:

$pagedListResponse = $client->getList(...);
foreach ($pagedListResponse as $element) {
    // doSomethingWith($element);
}

Example of iterating over each page of elements:

$pagedListResponse = $client->getList(...);
foreach ($pagedListResponse->iteratePages() as $page) {
    foreach ($page as $element) {
        // doSomethingWith($element);
    }
}

Example of accessing the current page, and manually iterating over pages:

$pagedListResponse = $client->getList(...);
$page = $pagedListResponse->getPage();
// doSomethingWith($page);
while ($page->hasNextPage()) {
    $page = $page->getNextPage();
    // doSomethingWith($page);
}

Methods

__construct(Page $firstPage)

PagedListResponse constructor.

iterateAllElements()

Returns an iterator over the full list of elements. If the API response contains a (non-empty) next page token, then the PagedListResponse object will make calls to the underlying API to retrieve additional elements as required.

getIterator()

Returns an iterator over the full list of elements. If the API response contains a (non-empty) next page token, then the PagedListResponse object will make calls to the underlying API to retrieve additional elements as required.

getPage()

Return the current page of results.

Page[]
iteratePages()

Returns an iterator over pages of results. The pages are retrieved lazily from the underlying API.

expandToFixedSizeCollection(int $collectionSize)

Returns a collection of elements with a fixed size set by the collectionSize parameter. The collection will only contain fewer than collectionSize elements if there are no more pages to be retrieved from the server.

iterateFixedSizeCollections(int $collectionSize)

Returns an iterator over fixed size collections of results.

Details

__construct(Page $firstPage)

PagedListResponse constructor.

Parameters

Page $firstPage

A page containing response details.

Generator iterateAllElements()

Returns an iterator over the full list of elements. If the API response contains a (non-empty) next page token, then the PagedListResponse object will make calls to the underlying API to retrieve additional elements as required.

NOTE: The result of this method is the same as getIterator(). Prefer using getIterator(), or iterate directly on the PagedListResponse object.

Return Value

Generator

Exceptions

ValidationException

Generator getIterator()

Returns an iterator over the full list of elements. If the API response contains a (non-empty) next page token, then the PagedListResponse object will make calls to the underlying API to retrieve additional elements as required.

Return Value

Generator

Exceptions

ValidationException

Page getPage()

Return the current page of results.

Return Value

Page

Page[] iteratePages()

Returns an iterator over pages of results. The pages are retrieved lazily from the underlying API.

Return Value

Page[]

Exceptions

ValidationException

FixedSizeCollection expandToFixedSizeCollection(int $collectionSize)

Returns a collection of elements with a fixed size set by the collectionSize parameter. The collection will only contain fewer than collectionSize elements if there are no more pages to be retrieved from the server.

NOTE: it is an error to call this method if an optional parameter to set the page size is not supported or has not been set in the original API call. It is also an error if the collectionSize parameter is less than the page size that has been set.

Parameters

int $collectionSize

Return Value

FixedSizeCollection

Exceptions

ValidationException

Generator|FixedSizeCollection[] iterateFixedSizeCollections(int $collectionSize)

Returns an iterator over fixed size collections of results.

The collections are retrieved lazily from the underlying API.

Each collection will have collectionSize elements, with the exception of the final collection which may contain fewer elements.

NOTE: it is an error to call this method if an optional parameter to set the page size is not supported or has not been set in the original API call. It is also an error if the collectionSize parameter is less than the page size that has been set.

Parameters

int $collectionSize

Return Value

Generator|FixedSizeCollection[]

Exceptions

ValidationException