jonatasfenske / paginator

v1.0.0 2026-11-13 19:01 UTC

Requires

• php: >=8.5

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0

MIT

• Robson V. Leite
• Jonatas Fenske

• bootstrap
• pagination
• infinite-scroll
• tailwind
• cursor-pagination
• php85

Published on Packagist.org on 2026-11-13 19:23 UTC

README

Paginação PHP 8.5 com suporte offset-based e cursor-based

Instalação

composer require jonatasfenske/paginator

Recursos

• Paginação offset-based — clássica, ideal para sites tradicionais e SEO
• Paginação cursor-based — performance O(1) constante, ideal para APIs e infinite scroll
• Templates CSS — Bootstrap 5, Tailwind CSS e minimalista
• Templates customizáveis — via PaginatorTemplate::register()
• Acessibilidade — atributos ARIA automáticos (aria-label, aria-current)
• Integração nativa com jonatasfenske/datalayer via paginate()
• Resposta JSON completa com meta para APIs REST

Uso Rápido

Paginação Offset (HTML)

use JonatasFenske\Paginator\Paginator;
use JonatasFenske\Paginator\PaginatorTemplate;

$pager = new Paginator();
$pager->pager(rows: 150, limit: 10, page: 3, range: 3);

// Template Bootstrap 5
echo PaginatorTemplate::render($pager, 'bootstrap');

// Template Tailwind CSS
echo PaginatorTemplate::render($pager, 'tailwind');

Paginação Cursor-Based (API)

use JonatasFenske\Paginator\CursorPaginator;

$paginator = new CursorPaginator(limit: 20, cursorColumn: 'id', direction: 'desc');

// Processar resultados da query (LIMIT + 1 para detectar hasMore)
$paginator->setCurrentCursor($_GET['cursor'] ?? null)->process($results);

header('Content-Type: application/json');
echo $paginator->toJson();
// {"data": [...], "meta": {"has_more": true, "next_cursor": "78", ...}}

Integração com DataLayer

$result = $postModel
 ->find('status = :s', 's=published')
 ->order('created_at DESC')
 ->paginate(page: 2, limit: 15);

foreach ($result['results'] as $post) { echo $post->title; }
echo $result['paginator']->render();

Helpers SQL do CursorPaginator

$where = $paginator->whereClause($cursor); // "id < :cursor"
$order = $paginator->orderByClause();      // "id DESC"

Testes

composer test

Licença

MIT