Custom data-source adapters

Lookahead

Implement LookaheadAdapterInterface to support lookahead(). Its sliceWithLookahead() method returns [items, hasMore] and must never return more than the requested limit.

Cursor

Implement CursorAdapterInterface to support cursor pagination. It receives a decoded CursorBoundary and returns a CursorSlice containing the items, the next boundary, the previous boundary and the hasNext state.

resolveCursorOrder() returns the effective CursorOrder. The cursor codec binds it to signed tokens before a boundary is decoded or created.

For a field-based source, validate the fields passed to orderBy() and append a unique tie-breaker when the source can derive one:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

public function resolveCursorOrder(
    mixed $source,
    ?array $fields,
    ?string $direction,
): CursorOrder {
    \assert($source instanceof SearchQuery);

    if (null === $fields || null === $direction) {
        throw new \InvalidArgumentException('Call orderBy() for this source.');
    }

    if (!\in_array('objectID', $fields, true)) {
        $fields[] = 'objectID';
    }

    return CursorOrder::byFields($fields, $direction);
}

For a remote connection that owns its order, reject an application-supplied field order and return a stable opaque identity. Callers then omit orderBy():

1
2
3
4
5
6
7
8
9
10
11
12
13

public function resolveCursorOrder(
    mixed $source,
    ?array $fields,
    ?string $direction,
): CursorOrder {
    \assert($source instanceof SearchQuery);

    if (null !== $fields || null !== $direction) {
        throw new \InvalidArgumentException('This API owns its cursor order.');
    }

    return CursorOrder::byIdentity('search:created_at_desc:v1');
}

Changing the opaque identity invalidates existing tokens. Include the remote sort mode or a version in it, but never credentials.

The adapter also implements getCursorContext(). Return a deterministic description of everything that defines the logical source query but is not already part of the order. The cursor codec binds this value to every signed token.

The second argument is the optional value supplied by the application through cursor()->context(). Include it when it scopes the source. A custom adapter may require it, ignore it, or combine it with source data, but the resulting context must be deterministic.

For a remote API, that context typically contains the endpoint, the filters and the tenant or repository identity. It must not contain the current page items:

1
2
3
4
5
6
7
8
9
10

public function getCursorContext(mixed $source, ?string $context): string
{
    \assert($source instanceof SearchQuery);

    return json_encode([
        'index' => $source->index,
        'filters' => $source->filters,
        'context' => $context,
    ], \JSON_THROW_ON_ERROR);
}