Implement pagination

[bilfeldt]

General

Paginated responses should implement the PaginatedApiResponseInterface and they can be used like so for a concrete API:

$apiResponse = $api->examples()->get(); // PaginatedExampleApiResponseInterface which extends the PaginatedApiResponseInterface

Interface

A PaginatedApiResponseInterface has a bunch of methods which are used to traverse the results and return the same response type.

Note that the return typehint for the pagination should be self since we require the same response type to be returned when traversing and not just a new PaginatedApiResponseInterface. This is covariance which is only implemented in PHP 7.4 as can be seen here hence to support pre PHP 7.4 versions we leave out the return typehint for the traversing methods.

The methods of the interface are:

$apiResponse->hasPrev(); // bool
$apiResponse->hasNext(); // bool
// These traversing methods should all return the same type as the $apiResponse itself
$apiResponse->prev(); // PaginatedExampleApiResponseInterface - Note return type 'self' left out for pre PHP7.4 compatibility
$apiResponse->next(); // PaginatedExampleApiResponseInterface - Note return type 'self' left out for pre PHP7.4 compatibility
$apiResponse->last(); // PaginatedExampleApiResponseInterface - Note return type 'self' left out for pre PHP7.4 compatibility

Note that prev() and next() can throw an OutOfRangeException if the pages are not there