Weave Code
Laravel Fast Paginate Laravel Package
spatie/laravel-fast-paginate
A fast limit/offset paginator for Laravel. The fastPaginate method selects only primary keys first so late pages stay fast, then fetches full rows for that page. Same signature and paginator as Laravel's paginate, so no other code changes.
A fast limit/offset paginator for Laravel
Frequently asked questions about Laravel Fast Paginate
- How do I install spatie/laravel-fast-paginate in a Laravel app?
- Install it with Composer using composer require spatie/laravel-fast-paginate. The service provider is auto-discovered, so there is no config file to publish or register manually. After that, call fastPaginate() instead of paginate() on any Eloquent query builder where you want the optimization.
- Is fastPaginate a drop-in replacement for Laravel's paginate method?
- Yes. The method signature is identical to Laravel's paginate, so you can pass perPage, columns, pageName, and page the same way. It returns the same paginator instance, which means existing API resources, Blade links, and front-end page controls keep working without changes.
- Which Laravel and PHP versions does laravel-fast-paginate support?
- The README excerpt does not state version constraints, so check the require section of composer.json on Packagist or in the repository before committing. Confirm the package is tested against your current Laravel and PHP versions plus your next planned upgrade. Running composer why-not spatie/laravel-fast-paginate quickly shows any conflict with your locked dependencies.
- How does fastPaginate make deep offset pages faster than paginate?
- It splits one wide query into two: first it runs your query selecting only the primary key, which the database can often satisfy entirely from an index. Then it fetches the full rows for just those keys on the requested page. This avoids reading and discarding wide columns for every row before the offset, which is where most of the cost on late pages comes from.
- Does fastPaginate make page 10000 as fast as page 1?
- No. The offset scan still happens at the index level, so cost grows with page depth, it is just much cheaper per row. The package reduces IO and column-fetch overhead rather than turning deep pagination into an O(1) operation. For truly constant-time deep navigation you need keyset or cursor pagination instead.
- What query shapes are unsafe or unsupported with fastPaginate?
- Queries using joins, groupBy, having, distinct, unions, or custom select clauses are the usual trouble spots, along with composite primary keys, global scopes, and soft deletes. Because the second phase re-fetches rows by primary key, anything that changes row semantics between the two queries can break results. Benchmark and assert output against paginate for every query shape you convert.
- Can fastPaginate return duplicate or missing rows when orderBy is not unique?
- Yes, that is the main correctness risk. The two-phase approach assumes a deterministic, unique ordering, so an orderBy on a non-unique column can shift rows between pages as the database resolves ties differently. Always append the primary key as a tiebreaker, for example orderBy('created_at')->orderBy('id'), and test pagination across several pages.
- Is fastPaginate safe for production with concurrent writes?
- The two queries are not wrapped in a transaction by default, so inserts, updates, or deletes between the key scan and the row fetch can produce a page that never existed as a consistent snapshot. That is acceptable for browse-style lists such as admin tables and activity feeds. Avoid it for exports, financial reports, or audit views where snapshot consistency matters, or wrap the call in a transaction at the cost of holding locks.
- Should I use fastPaginate or Laravel's cursorPaginate?
- They solve different problems. cursorPaginate avoids the offset scan entirely and stays fast at any depth, but it changes the paginator contract and gives up page numbers and total counts, so front-end page controls need rework. fastPaginate keeps the standard length-aware paginator, making it the lower-risk option when you need numbered pages over large but browsable tables.
- How do I test fastPaginate, and what if the package is abandoned?
- Write feature tests that run the same query with paginate and fastPaginate and assert identical IDs, ordering, and totals per page, including the last page and a non-unique sort order. The package ships a test suite run via GitHub Actions, so check the badge and pinned version before adopting. Adoption signals are thin, but the surface area is small enough that the two-phase logic could be reproduced in-house if maintenance stalls.
Weaver
How can I help you explore Laravel packages today?