PHP REST API Cursor Pagination

Produce deterministic pages using a last-seen ordering key rather than OFFSET. The examples separate the essential operation from the conditions a production implementation must enforce.

What It Does

Produce deterministic pages using a last-seen ordering key rather than OFFSET.

Prerequisites

Use a dedicated development environment with test accounts and records. Separate authorization, validation and error handling from response formatting; never copy demonstration-only secrets into production.

Example 1: Core Behavior

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$rows=[["id"=>4],["id"=>8],["id"=>10]]; $after=4; echo json_encode(array_values(array_filter($rows,fn($r)=>$r["id"]>$after)));

Example 2: Alternative or Failure Case

This scenario applies the exact rule described in the guide, with controlled sample values.

<?php
$cursor=base64_encode(json_encode(["lastId"=>83],JSON_THROW_ON_ERROR));echo rawurlencode($cursor);

Practical Example: Applying the Rule

This practical workflow performs the relevant operation, with strict error checks. Configure the required transport or database driver before running it.

<?php
$pdo = new PDO('sqlite::memory:', null, null, [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$pdo->exec('CREATE TABLE items (id INTEGER PRIMARY KEY, name TEXT)');
$pdo->exec("INSERT INTO items VALUES (1,'Desk'),(2,'Lamp'),(3,'Chair'),(4,'Shelf')");
$afterId = 2; $limit = 2;
$stmt = $pdo->prepare('SELECT id, name FROM items WHERE id > :after ORDER BY id ASC LIMIT :max');
$stmt->bindValue(':after', $afterId, PDO::PARAM_INT);
$stmt->bindValue(':max', $limit, PDO::PARAM_INT);
$stmt->execute();
$items = $stmt->fetchAll(PDO::FETCH_ASSOC);
$next = count($items) === $limit ? (int) end($items)['id'] : null;
echo json_encode(['items' => $items, 'next' => $next], JSON_THROW_ON_ERROR);

Important Behavior and Edge Cases

Cursor tokens must preserve direction and filter context; tie-break equal sort values.

Comparison with Related Functions or Patterns

Common Beginner Mistakes

Key Takeaways

• Produce deterministic pages using a last-seen ordering key rather than OFFSET.
• Cursor tokens must preserve direction and filter context; tie-break equal sort values.
• Limit/offset pagination can become inconsistent when rows move between requests.

Select this API or pattern based on its documented behavior and the trust boundaries in your own application, and test all external integrations against their actual deployments.