README

The fetching half of cursor pagination for PHP.

You implement one method, fetchPage(?string $cursor): Page, that turns one upstream response into one page. cursor-walk owns the loop around it: threading the cursor, fetching each page only when iteration reaches it, resuming from a checkpoint, stopping runaway upstreams, and cutting exact-N slices for a Relay first. It works against a REST API, a GraphQL API, a DynamoDB scan, or anything else that says "here is a page, here is the cursor for the next one".

Why this one

Lazy by construction. One upstream call per page, made when iteration crosses into it. A client asking for 25 items from 100-item pages costs one call, not the whole dataset in memory.
Guarded by default. A repeated cursor throws. An upstream that hands out fresh cursors forever hits a page budget, and the exception carries the cursor to resume from.
Resumable. Every endCursor is a checkpoint, so a batch job that dies halfway picks up at the page it was on.
Exact slices. slice() assembles exactly first items across as many fetches as it takes, even when the end lands in the middle of an upstream page.
Relay output with no GraphQL dependency. ConnectionFormatter returns a plain edges / pageInfo array that a resolver can return as is.
Any cursor, any transport. Opaque tokens, page numbers and row offsets all work, because the engine never looks inside a cursor. The library makes no requests of its own, and require is php alone.

Install

composer require ryckakas/cursor-walk

PHP 8.2 or newer. No runtime dependencies.

Use it

Implement PaginatedFetcher, the only integration point: one upstream response in, one Page out.

use CursorWalk\Page;
use CursorWalk\PaginatedFetcher;
use CursorWalk\Paginator;

/** @implements PaginatedFetcher<array{id: int, name: string}> */
final class WidgetFetcher implements PaginatedFetcher
{
    public function __construct(private readonly WidgetApi $api) // your HTTP client, SDK, anything
    {
    }

    public function fetchPage(?string $cursor): Page
    {
        $response = $this->api->listWidgets(limit: 100, after: $cursor);

        return new Page($response['data'], $response['next_cursor'] ?? null, $response['has_more']);
    }
}

$paginator = new Paginator();

foreach ($paginator->items(new WidgetFetcher($api)) as $widget) {
    // Page 2 is fetched when the loop reaches item 101, not before.
}

The same fetcher over a PSR-18 client, validating the envelope

use CursorWalk\Exception\MalformedPageException;
use CursorWalk\Page;
use CursorWalk\PaginatedFetcher;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;

/** @implements PaginatedFetcher<array{id: int, name: string}> */
final class WidgetFetcher implements PaginatedFetcher
{
    public function __construct(
        private readonly ClientInterface $http,
        private readonly RequestFactoryInterface $requests,
    ) {
    }

    public function fetchPage(?string $cursor): Page
    {
        $url = 'https://api.example.com/widgets?limit=100'
            . ($cursor === null ? '' : '&after=' . urlencode($cursor));

        $body = (string) $this->http->sendRequest($this->requests->createRequest('GET', $url))->getBody();
        $data = json_decode($body, true);
        if (!is_array($data) || !isset($data['data']) || !is_array($data['data'])) {
            throw MalformedPageException::invalidEnvelope('missing "data" key', $cursor, $body);
        }

        return new Page(
            items: array_values($data['data']),
            endCursor: $data['next_cursor'] ?? null,
            hasNextPage: (bool) ($data['has_more'] ?? false),
            totalCount: $data['total'] ?? null,
        );
    }
}

Snippets omit declare(strict_types=1);. The library declares it in every file, and your fetchers should too.

Paginator is stateless: inject one and reuse it. It has three methods.

Method	Returns	Use it for
`items($fetcher, ?string $pageCursor = null, int $skip = 0)`	`Generator<int, T>`	Streaming every item.
`pages($fetcher, ?string $startCursor = null)`	`Generator<int, Page<T>>`	Batch jobs: one transaction, retry and checkpoint per page.
`slice($fetcher, int $first, ?string $pageCursor = null, int $skip = 0)`	`Page<T>`	Exactly N items, such as a Relay `first`.

The page budget

new Paginator() stops after 10,000 pages and throws PageBudgetExceededException, whose getLastCursor() resumes the walk. Loop detection catches a cursor that repeats, but not an upstream that returns a fresh cursor with hasNextPage: true forever. The budget does. Size it to the caller, not the dataset:

$interactive = new Paginator(maxPages: 50);      // an API request: fail fast
$batch       = new Paginator(maxPages: 100_000); // a nightly sync: still bounded
$unbounded   = new Paginator(maxPages: null);    // no limit, and the risk is yours

Why the budget is on by default, and what null costs, is in the design notes.

When a walk fails

Exception	Meaning	Typical response
`MalformedPageException`	The upstream response is not a usable page.	Log `getCursor()` and `getRawContext()`; retry or fail the request.
`PaginationLoopException`	A cursor repeated, so the walk would never end.	A bug upstream or in the fetcher. Do not retry.
`PageBudgetExceededException`	Your `maxPages` was reached.	Resume from `getLastCursor()`, or raise the budget.

All three extend CursorWalk\Exception\CursorWalkException, a \RuntimeException. Page itself throws MalformedPageException for the one combination it refuses: hasNextPage: true with no endCursor. Anything stricter belongs in your fetcher; see rejecting malformed pages.

Recipes

A GraphQL resolver returning a Relay connection: slice() and ConnectionFormatter, with edge cursors that round-trip as after.
Batch jobs that checkpoint per page: pages() as the transaction and retry boundary.
Resuming a walk: from a checkpoint, a client's cursor, or an exhausted page budget.
Page-numbered and offset upstreams: ?page=2 and ?offset=100 APIs through PageNumberFetcher and OffsetFetcher.
Driving the walk yourself: Walk, for Temporal workflows and event loops that cannot let the library call fetchPage().
Rejecting malformed pages: stricter upstream policy in the fetcher, and catching each failure separately.

Important

The default Relay edge cursor names a position, not an item, so it can repeat or skip rows if the upstream changes between requests. Read cursor stability before storing one.

Documentation

Recipes: the patterns above, in full
Design notes: the guards, cursor stability, what it deliberately does not do, and how it fits with webonyx/graphql-php, graphql-relay-php and relay-pagination
Roadmap: what is likely to come next, and why
Changelog: what changed in each release

Development

Commands and gates

composer check      # code style, static analysis, complexity, tests, offline example
composer check:ci   # everything CI runs, adding coverage, mutation and the public API check

check:ci needs xdebug or pcov. The complexity gate is bonsai-lint, a dev dependency like the rest. composer bc fails on any break of the public API since the latest release, using Roave BackwardCompatibilityCheck; it needs PHP 8.4+ and composer install -d tools/bc-check once. CI also audits the workflows with zizmor. AGENTS.md has the conventions.

License

MIT. See LICENSE.

ryckakas / cursor-walk

Package info

Security

Statistics