Lib Pagination Laravel Package

Product Decisions This Supports

• Public API pagination strategy. Cursor-based pagination is the right default for list endpoints that back infinite scroll, feeds, activity streams, search results, and audit/history views, because it stays stable when rows are inserted or deleted between pages and avoids the deep-OFFSET performance cliff. This package gives you both cursor and offset modes from one Doctrine QueryBuilder, so you can standardize on one contract without writing cursor encoding/decoding, ordering tie-breakers, and filter-preserving links yourself.
• Build vs. buy for a non-differentiating concern. Pagination is infrastructure, not product. The build path is 1–3 engineer-days plus ongoing edge-case maintenance (stable sort keys, cursor opacity, empty/short pages, filter changes mid-scroll). The buy path is a small MIT-licensed dependency. Lean buy unless you have unusual pagination semantics.
• Roadmap sequencing for API v2 / mobile clients. If a mobile or partner-integration roadmap needs cursor pagination, this can unblock that work without pulling a platform engineer into a pagination sub-project.
• Doctrine-based service decisions. This is a real constraint, not a detail: the package targets Doctrine QueryBuilder. If the surface in question is Eloquent, it does not apply. If you run Doctrine inside Laravel (e.g., laravel-doctrine) or in a Symfony/standalone PHP service, it is applicable.
• Use cases worth validating in discovery: high-volume transaction/ledger lists (Paysera's own domain — payments history), notification and event feeds, admin tables with millions of rows, and any endpoint where clients currently paginate by page number and complain about duplicates or drift.

When to Consider This Package

Consider it when all of the following hold:

• The query layer is Doctrine QueryBuilder (or you can adapt it), not Eloquent.
• You need cursor pagination, or you need to offer both cursor and offset from the same query contract.
• Your datasets are large enough that OFFSET cost or page drift is a real user-visible or cost problem.
• You are comfortable vendoring or forking a small MIT library: the code footprint is modest, so the escape hatch is cheap.
• You can verify maintenance cadence yourself. The metadata shows a very recent release date (2026-09-29), which reads as actively maintained, but with only ~14 stars the public signal is thin — confirm commit history, open issues, and test coverage in the repo before committing.

Look elsewhere when:

• Your stack is Eloquent-first Laravel. Use cursorPaginate(); adopting Doctrine just to use this library is a bad trade.
• You need a framework bundle with DI config, Twig/Blade helpers, and pagination UI out of the box — evaluate Symfony's Pagerfanta/KnpPaginatorBundle or API Platform's built-in pagination instead.
• You need vendor support, SLAs, security response commitments, or a named maintainer on retainer. 14 stars means effectively a bus factor of one; treat it as "adopt the code, not the vendor."
• You need rich metadata (total counts, page counts) as a first-class feature — cursor pagination inherently gives that up, and offset mode with COUNT(*) on large tables is exactly what you were trying to escape.
• Licensing is a blocker — it is not: MIT permits commercial use, modification, and redistribution with attribution.

How to Pitch It (Stakeholders)

To executives (one paragraph): We have a recurring, low-glamour problem: list endpoints that paginate by page number break when data changes underneath the user and get slower as users scroll deeper. Fixing it properly is a small but fiddly piece of engineering that we would otherwise rebuild in every service. A focused MIT-licensed library from Paysera — a payments company that has clearly solved this for its own transaction data — already implements both cursor-based and offset-based pagination over Doctrine queries. The recommendation is to adopt it as a narrow, replaceable utility, not a platform commitment: it is small enough to fork if it stalls, and it removes a category of API bugs and a recurring engineering chore. It is not a strategic bet and should not appear on an architecture diagram.

To engineering (the honest version): It does one thing — paginate a Doctrine QueryBuilder — with both cursor and offset modes. Upside: correct cursor semantics without us rediscovering the tie-breaker and filter-preservation edge cases, MIT license, small surface area, cheap to vendor. Downsides: ~14 GitHub stars, essentially single-vendor provenance, and Doctrine-only, so it is inert if this service is Eloquent. Plan to pin the version, vendor or mirror the source, read the implementation before trusting it in a hot path, and wrap it behind our own pagination interface so swapping it out is a one-file change. If those conditions are acceptable, it saves us a few days and a class of production bugs; if not, we write ~200 lines and own it outright.