wwwision / relay-pagination
Simple pagination implementing the Cursor Connections Specification, see https://relay.dev/graphql/connections.htm
Fund package maintenance!
bwaidelich
Paypal
Installs: 3 450
Dependents: 1
Suggesters: 0
Security: 0
Stars: 3
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >= 8.1
- webmozart/assert: ^1.10
Requires (Dev)
- phpunit/phpunit: ^9
Suggests
- doctrine/dbal: To make use of the DbalLoader
- doctrine/orm: To make use of the OrmLoader
README
Simple pagination implementing the Cursor Connections Specification, see https://relay.dev/graphql/connections.htm
Installation
Install via composer:
composer require wwwision/relay-pagination
Usage
$loader = # ... instance of \Wwwision\RelayPagination\Loader\Loader $resultsPerPage = 5; // edges to load per page $paginator = new Paginator($loader); $firstPage = $paginator->first($resultsPerPage); foreach ($firstPage as $edge) { // $edge->cursor; contains the cursor string // $edge->node; contains the payload } // $firstPage->pageInfo; contains an object with pagination information
Next page(s)
Every connection
contains information about next and previous pages.
To navigate to a succeeding page, you can use the endCursor
of the previous connection as input for the after
argument:
if ($firstPage->pageInfo->hasNextPage) { $secondPage = $paginator->first($resultsPerPage, $firstPage->pageInfo->endCursor); // ... }
Backwards navigation
To navigate to a preceeding page, the startCursor
can be passed to the last()
method likewise:
if ($secondPage->pageInfo->hasPreviousPage) { $firstPage = $paginator->last($resultsPerPage, $secondPage->pageInfo->startCursor); // ... }
Reversed order
The ordering of edges is the same whether forward or backward navigation is used (as defined in the specification).
To navigate through results in reversed order, the reversed()
method of the Paginator
can be used:
$loader = new ArrayLoader(range('a', 'e')); $paginator = (new Paginator($loader))->reversed(); $page1 = $paginator->first(3); Assert::same(['e', 'd', 'c'], array_map(fn($edge) => $edge->node, $page1->toArray())); Assert::false($page1->pageInfo->hasPreviousPage); Assert::true($page1->pageInfo->hasNextPage); $page2 = $paginator->first(3, $page1->pageInfo->endCursor); Assert::same(['b', 'a'], array_map(fn($edge) => $edge->node, $page2->toArray())); Assert::true($page2->pageInfo->hasPreviousPage); Assert::false($page2->pageInfo->hasNextPage);
Loaders
This package comes with four adapters (aka "loaders"):
ArrayLoader
The ArrayLoader
allows to paginate arbitrary arrays.
Note: This loader is mainly meant for testing and debugging purposes and it should not be used for large datasets because the whole array has to be loaded into memory, obviously.
Usage
$arrayLoader = new ArrayLoader($arbitraryArray);
Note: The specified array can be associative, but the keys will be lost during pagination since the ArrayLoader only works with the array values in order to guarantee deterministic ordering.
CallbackLoader
The CallbackLoader
invokes closures to determine pagination results.
Note: This loader is mainly meant for rapid development, testing & debugging purposes. Usually you'd want to create a custom implementation of the Loader interface instead
Usage
$callbackLoader = new CallbackLoader( fn(int $limit, string $startCursor = null) => Edges::fromRawArray(...), fn(int $limit, string $endCursor = null) => Edges::fromRawArray(...) );
DbalLoader
The DbalLoader
allows to paginate arbitrary DBAL results.
Note: This loader requires the doctrine/dbal
package to be installed:
composer require doctrine/dbal
Usage
$queryBuilder = (new QueryBuilder($dbalConnection)) ->select('*') ->from('some_table'); $dbalLoader = new DbalLoader($queryBuilder, 'id');
OrmLoader
The OrmLoader
allows to paginate arbitrary Doctrine ORM results.
Note: This loader requires the doctrine/orm
package to be installed:
composer require doctrine/orm
Usage
$queryBuilder = $entityManager->createQueryBuilder() ->select('e') ->from(SomeEntity::class, 'e'); $ormLoader = new OrmLoader($queryBuilder, 'id');
Convert nodes
A node
is the only untyped property in this package since the loaders define the structure & type of nodes.
For the DbalLoader
a node is an associative array containing the raw result from the corresponding database row for example.
In order to make it easier to re-use loaders a Node Converter
can be specified that is applied to all results before it is returned:
$paginator = (new Paginator($someLoader)) ->withNodeConverter(fn(string $node) => json_decode($node));
The above example expects the nodes to contain a valid JSON string. The same mechanism can be used in order to convert database results to a dedicated domain model instance:
$paginator = (new Paginator($dbalLoader)) ->withNodeConverter(fn(array $row) => MyModel::fromDatabaseRow($row));