Пагинация

Отдать десять тысяч строк одним ответом нельзя ни клиенту, ни памяти воркера. Разрезать выборку можно двумя способами, и они не взаимозаменяемы: смещение удобно, курсор корректен. Ниже — чем они отличаются на живых данных, и разбор каждого метода: что принимает, что возвращает, что делает на краях.

Что такое пагинация

Выдача результата частями: клиент получает окно и способ запросить следующее. Окно задаётся двумя числами — сколько строк и откуда начинать, — а «откуда» бывает двух видов, и в этом вся разница.

Смещение — «пропусти 40, дай 20». Это LIMIT/OFFSET, номера страниц, почти все админки.

Курсор — «дай 20 после вот этой позиции». Позиция — значение колонки последней отданной строки, упакованное в непрозрачный токен.

Смещение или курсор

Разница выглядит вкусовой ровно до момента, когда данные меняются между двумя запросами:

Страница 1: id 12, 11, 10, 9   ← пользователь читает
           ↓ кто-то добавил запись
Смещение:   OFFSET 4 → 9, 8, 7, 6      ← id 9 показан дважды
Курсор:     после id 9 → 8, 7, 6, 5    ← ничего не задвоилось и не пропало

Вставка сдвигает все смещения, поэтому строка на границе показывается второй раз, а при удалении — пропадает незамеченной. Курсор привязан к значению, а не к номеру.

Вторая разница — цена. OFFSET 100000 заставляет базу пройти и отбросить сто тысяч строк; курсор превращается в WHERE id < :значение и берёт индекс.

Где что применяют

Справочник методов

Paginator

Возвращает PaginationResult — конверт из meta и data. Все три метода статические.

repo()

public static function repo(
  RepositoryViewInterface $repo,
  int $size,
  int $offset = 0,
  ?string $entityClassName = null,
  ?callable $mapper = null,
): PaginationResult

Страница по смещению из репозитория.

$repo — не имя таблицы, а собранный запрос: условия, джойны и сортировка ставятся до пагинации, и она их не меняет.

Paginator::repo(
  PostRepository::instance('p')
      ->where(Qb::eq('p.status', 'published'))
      ->orderBy('p.created_at DESC'),
  size: 20,
);

$size — только положительное. 0 или отрицательное — не пустая страница, а ошибка:

ValueError: Size must be a positive integer (>= 1), got: 0.

$offset может уйти за конец — это не ошибка. Данные будут пустыми, а total по-прежнему честным, и по нему клиент поймёт, что промахнулся:

{ "meta": { "offset": 99, "size": 5, "total": 9 }, "data": [] }

$entityClassName подменяет класс, в который гидрируются строки. Полезно, когда одна таблица отдаётся в разных формах — но подменяется только класс, не набор колонок:

Paginator::repo($repo, size: 2, entityClassName: Slim::class);
// у Slim объявлены id и title, но в строке пришёл ещё views —
// Deprecated: Creation of dynamic property Slim::$views

Чтобы сузить набор колонок, сужайте select() у репозитория; $entityClassName для этого не предназначен.

$mapper получает уже гидрированный объект (сущность репозитория либо $entityClassName), а не массив строки. Возвращённое значение занимает место элемента:

$page = Paginator::repo($repo, size: 2, mapper: fn(Post $p) => $p->title);
$page->data;   // ["t1", "t2"]

Вызывается он только на строках страницы — остальные не гидрируются вовсе.

Возвращает PaginationResult с PaginationMeta (offset, size, total).

array()

public static function array(
  array $items,
  int $size,
  int $offset = 0,
  ?callable $mapper = null,
): PaginationResult

То же самое для готового списка. Соединение не открывается.

$items передаётся весь: total — это его длина, поэтому метод знает общее число без запросов. Обратная сторона очевидна — список уже должен быть в памяти.

Возвращает PaginationResult с той же PaginationMeta, что и repo(), — формы совпадают, поэтому источник можно поменять, не трогая клиента.

$page = Paginator::array($rowsFromApi, size: 10, offset: 20);

Нужен, когда данные пришли не из базы — из внешнего API, из кеша, из файла, — а отдавать их надо в том же конверте, что и всё остальное.

cursor()

public static function cursor(
  RepositoryViewInterface $repo,
  int $size,
  CursorKey $key,
  ?string $cursor = null,
  ?string $entityClassName = null,
  ?callable $mapper = null,
): PaginationResult

Страница «после позиции».

$key задаёт и позицию, и порядок: из него строится ORDER BY, из него же берётся значение для WHERE. Свой orderBy() на репозитории здесь не нужен — он не согласован с условием «после позиции», и страницы начнут перекрываться.

$cursor — то, что клиент вернул из meta.cursorNext или meta.cursorPrev. null означает «с начала», и это единственный способ начать: номера страниц у курсора нет.

$key = new CursorKey('id', Sort::Desc);

$page = Paginator::cursor(
  PostRepository::instance(),
  size: 20,
  key: $key,
  cursor: $request->query('cursor'),
);

return ResponseEntity::ok($page);

Возвращает PaginationResult с PaginationMetaCursor (size, cursorPrev, cursorNext). Бросает InvalidCursorException, если токен испорчен или выпущен под другой ключ.

На краях токены равны null — по ним и рисуются кнопки:

// первая страница
{ "meta": { "size": 4, "cursorPrev": null, "cursorNext": "eyJzIjoi…" }, "data": [ … ] }

// последняя
{ "meta": { "size": 5, "cursorPrev": "eyJzIjoi…", "cursorNext": null }, "data": [ … ] }

Wrapper

Тот же обход по смещению, но мета описана страницами, а не смещением. Это то, что нужно интерфейсу с номерами: клиенту не приходится делить total на size и считать соседей самому.

paginator()

public static function paginator(
  RepositoryViewInterface|array $repo,
  int $limit,
  int $page = 1,
  ?string $entityClassName = null,
  ?callable $mapper = null,
): WrapResult

$repo принимает оба вида источника, и это главное отличие от Paginator. С массивом метод не открывает соединения — режет список на месте:

Wrapper::paginator(range(1, 25), limit: 10, page: 2);
// {"meta":{"current":2,"size":10,"total":25,"pages":3,"previous":1,"next":3},
//  "data":[11,12,13,14,15,16,17,18,19,20]}

$page считается с единицы, а не с нуля: page: 1 — первая страница, смещение 0. Внутри оно и вычисляется как limit × (page − 1).

$entityClassName для массива игнорируется молча — гидрировать нечего, элементы отдаются как есть:

Wrapper::paginator([1, 2, 3, 4], limit: 2, entityClassName: Slim::class);
// data: [1, 2] — никакой гидрации не произошло

Возвращает WrapResult с WrapMeta. Поля меты считаются так:

$result = Wrapper::paginator(PostRepository::instance(), limit: 5, page: 2);

{
"meta": {
  "current": 2,      // запрошенная страница
  "size": 5,         // размер страницы
  "total": 12,       // всего строк — тот самый COUNT
  "pages": 3,        // ceil(total / size)
  "previous": 1,     // current − 1, либо null на первой
  "next": 3          // current + 1, если pages > current, иначе null
},
"data": [ { "id": 6 }, { "id": 7 }, { "id": 8 }, { "id": 9 }, { "id": 10 } ]
}

previous и next равны null на краях, поэтому клиент рисует стрелки прямо по ним, без собственной арифметики.

{"meta":{"current":9,"size":5,"total":9,"pages":2,"previous":8,"next":null},"data":[]}

Пустой источник даёт pages: 0, а не одну пустую страницу — страниц действительно нет:

{"meta":{"current":1,"size":5,"total":0,"pages":0,"previous":null,"next":null},"data":[]}

CursorKey

Описывает позицию: по какой колонке идти, в какую сторону и чем разрешать ничью.

new CursorKey(
  string $column,
  Sort $direction = Sort::Desc,
  ?CursorKey $tiebreaker = null,
  ?string $alias = null,
)

$column — это то, по чему сравнивают. Колонка должна быть в выборке: из неё берётся значение для токена. Для джойнов пишут её с алиасом таблицы (p.created_at).

$direction задаёт и порядок, и смысл сравнения: Desc — «строки меньше значения», Asc — «больше». При движении назад направление инвертируется автоматически.

$alias нужен, когда в SELECT колонка переименована (p.created_at AS posted_at): сравнивать надо по p.created_at, а читать значение — из posted_at.

Тай-брейкер: зачем он обязателен

Курсор — это «строки после этого значения». Если строк с одинаковым значением больше, чем размер страницы, граница перестаёт быть однозначной: база вправе вернуть их в любом порядке, и часть потеряется или повторится.

// плохо: у сотни постов одинаковый created_at
$key = new CursorKey('created_at', Sort::Desc);

// хорошо: ничья разрешается уникальным ключом
$key = new CursorKey('created_at', Sort::Desc,
  tiebreaker: new CursorKey('id', Sort::Desc));

С цепочкой в токен попадают оба значения, и сравнение идёт по паре:

ключ: views DESC, затем id DESC
стр. 1 → (id 8, views 2), (id 5, views 2), (id 2, views 2)
токен  → {"s":"bfe46c74","v":[2,2],"d":"f"}
стр. 2 → (id 7, views 1), (id 4, views 1), (id 1, views 1)

Правило: последний ключ цепочки должен быть уникальным. Обычно это первичный ключ.

Служебные методы

signature() — то, чем токен привязан к ключу: она лежит внутри курсора и сверяется при чтении. Поменяли сортировку — старые токены перестают подходить и дают ошибку вместо страницы, собранной по другому порядку.

Формы ответа

Все конверты реализуют JsonSerializable, поэтому возвращаются из контроллера как есть.

PaginationResult

PaginationMeta

Отдают repo() и array().

size — это запрос, а не факт: на последней странице строк придёт меньше. Считать пришедшие нужно по count($result->data).

PaginationMetaCursor

Отдаёт cursor(). Числа total здесь нет — курсор его не вычисляет, в этом и экономия.

WrapMeta

Отдаёт Wrapper::paginator().

Что внутри курсора

Токен непрозрачен для клиента, но не зашифрован — это base64 от небольшого JSON:

eyJzIjoiZGI4MTRhYWMiLCJ2IjpbOV0sImQiOiJmIn0=
  ↓ base64_decode
{"s":"db814aac","v":[9],"d":"f"}
 s — подпись ключа   v — значения позиции   d — направление (f — вперёд, b — назад)

Ошибки

Второй случай — обычная жизнь: ссылку скопировали не целиком. Третий — вы поменяли сортировку, а у клиента остался старый токен.

try {
  $page = Paginator::cursor($repo, size: 20, key: $key, cursor: $request->query('cursor'));
} catch (InvalidCursorException) {
  // токен не наш или испорчен — показываем первую страницу
  $page = Paginator::cursor($repo, size: 20, key: $key);
}

Отдельное исключение здесь не педантизм: молча начать с начала — значит показать пользователю первую страницу там, где он ждал продолжения, и не оставить следа в логах. Пакет сообщает о проблеме; начать заново или ответить 400 — решает приложение.

Дальше

• Репозитории — как собрать выборку, которую вы пагинируете
• Пул соединений — почему второй запрос за COUNT стоит внимания
• PPA — слой целиком