Service » Pagination

Paginate query results using MondocPaginationHelper, with support for both skip/offset pagination and cursor-style ObjectId pagination.

About pagination

Mondoc provides two pagination strategies: skip/offset pagination (page 1, 2, 3…) and ObjectId cursor pagination (load more, infinite scroll). Both share the same MondocPaginationHelper object, which carries the total result count, the current page, the per-page limit, and optionally a filter array.

Skip / offset pagination

Use getPaginationHelper() to build a helper, then pass it to getPage() to retrieve the results for that page.

  • getPaginationHelper(int $currentPage, int $perPage, array $filter = []): MondocPaginationHelper
    Counts the total number of documents matching $filter, then returns a configured MondocPaginationHelper instance. The filter is stored inside the helper so it can be passed automatically to getPage().
  • getPage(MondocPaginationHelper $paginator, ?string $sortByField = '_id', int $sortDirection = -1): array
    Returns the array of models for the current page described by the helper. The filter stored inside the helper is used automatically. Sort direction is -1 (descending) by default. 
<?php
$currentPage = (int)($_GET['page'] ?? 1);
$perPage     = 20;

$paginator = MyService::getPaginationHelper($currentPage, $perPage, ['active' => true]);
$results   = MyService::getPage($paginator, 'createdAt', -1);

echo 'Page ' . $paginator->getCurrentPage() . ' of ' . $paginator->getTotalPages();
echo ' (' . $paginator->getTotalResults() . ' total)';

ObjectId cursor pagination

Cursor pagination avoids the cost of large skips. Instead of a page number, you pass the last-seen ObjectId on each request. Mondoc uses it as a boundary ($lt or $gt) rather than counting an offset.

  • getPaginationHelperForObjectIdPagination(int $perPage, array $filter = []): MondocPaginationHelper
    Returns a helper configured for ObjectId cursor pagination. The total result count is still calculated so the helper can report total pages and results.
  • getPageByByObjectIdPagination(MondocPaginationHelper $paginator, ObjectId|string|null $currentId, int $sortDirection = -1): array
    Returns a page of models relative to $currentId. Pass null to start from the beginning. Pass the last ObjectId from the previous batch to fetch the next batch. $sortDirection controls whether results are ordered descending (-1) or ascending (1). 
<?php
// First page (no cursor yet)
$paginator = MyService::getPaginationHelperForObjectIdPagination(20, ['active' => true]);
$results   = MyService::getPageByByObjectIdPagination($paginator, null, -1);

// Next batch — pass the ObjectId of the last item returned
$lastId    = end($results)->getObjectId();
$paginator = MyService::getPaginationHelperForObjectIdPagination(20, ['active' => true]);
$results   = MyService::getPageByByObjectIdPagination($paginator, $lastId, -1);

The MondocPaginationHelper object

Both methods above return a MondocPaginationHelper instance. You can also create one directly with MondocPaginationHelper::init() if you already know the total count.

  • getCurrentPage(): int
    Returns the current page number.
  • getTotalPages(): int
    Returns the total number of pages.
  • getTotalResults(): int
    Returns the total document count matching the filter.
  • getLimit(): int
    Returns the per-page limit used in queries.
  • getSkip(): int
    Returns the calculated query skip/offset for the current page.
  • isFirstPage(): bool
    Returns true if the current page is page 1.
  • isLastPage(): bool
    Returns true if the current page is the last page.
  • hasMultiplePages(): bool
    Returns true if there is more than one page of results.
  • hasPreviousPage(): bool
    Returns true if there is a page before the current one.
  • hasNextPage(): bool
    Returns true if there is a page after the current one.
  • getFilter(): array
    Returns the filter array stored in the helper.
  • shouldShowPageOnUi(int $proposed, ?int $howManyPagesEachSide): bool
    Useful for rendering page-number lists. Returns true if the proposed page number falls within $howManyPagesEachSide pages of the current page. Pass null to show all pages.
  • asArray(): array
    Returns a serialisable array with keys page, pages, results, and perPage. Useful for JSON API responses.

Rendering page numbers

Use shouldShowPageOnUi() to build a windowed pagination UI without rendering every page number when there are hundreds of pages. 

<?php
$paginator = MyService::getPaginationHelper($currentPage, 20, []);

for ($p = 1; $p <= $paginator->getTotalPages(); $p++) {
    if ($paginator->shouldShowPageOnUi($p, 2)) {
        // render link for page $p
    }
}
Recommended reading:
Query scopesfast_rewind fast_forward Atomic operations