Weave Code
Cursor Pagination Laravel Package
laravel-json-api/cursor-pagination
Cursor-based pagination for Laravel JSON:API. Adds a cursor paginator so your JSON:API endpoints can page through large datasets efficiently, avoiding offset limits and keeping results stable as records change.
Laravel JSON:API cursor pagination implementation.
Frequently asked questions about Cursor Pagination
- What is laravel-json-api/cursor-pagination used for?
- It adds cursor-based pagination to APIs built on the laravel-json-api server stack, supplying a cursor Page implementation that emits spec-shaped links and meta. Endpoints can use page[cursor] and page[size] instead of the framework's default offset strategy. It is meant for JSON:API surfaces you have already committed to, not as a reason to adopt JSON:API.
- How do I install and register cursor pagination in Laravel JSON:API?
- Install it with Composer using laravel-json-api/cursor-pagination, then register the cursor page per JSON:API resource following the package documentation. The package supplies the pagination class, while the parent framework still owns content negotiation, serialization, error rendering, and link generation. Size the work as one review per endpoint rather than a single installation.
- Does this package replace Laravel's native cursorPaginate()?
- No. Laravel's native cursorPaginate() is the correct primitive for plain REST, API Resources, Fractal, or query-builder APIs. This package is specifically a pagination-profile add-on for laravel-json-api and has no integration surface outside that stack.
- Which Laravel and laravel-json-api versions does this package support?
- The exact constraints are defined in the package's composer.json and Packagist metadata, so verify them before planning. The provided evaluation context does not list supported Laravel or laravel-json-api majors. Because parent Page contract changes can require manual compatibility work, test against the specific parent version you run.
- How do page[cursor] and page[size] work with this package?
- The cursor Page implementation lets endpoints accept page[cursor] and page[size] query parameters and return JSON:API-shaped links and meta. Cursor values are opaque to clients and should not be decoded or constructed by hand. Your application still has to enforce authorization on the filtered dataset.
- Why does cursor pagination skip or duplicate rows?
- Keyset pagination requires a deterministic unique sort tuple, typically created_at plus id, and a composite index that matches it. Without that tiebreaker, records with equal sort values can move between pages and cause skipped or duplicated rows. The package cannot enforce the tiebreaker, so make it a per-endpoint prerequisite and require index sign-off before shipping.
- Can I show page numbers or total counts with cursor pagination?
- Generally no. Cursor pagination trades jump-to-page, arbitrary page addressing, and cheap totals for stable, inexpensive deep pages. That suits infinite scroll, background sync, exports, and activity logs, но not admin tables that need page 7 of 42. Decide this per client surface before adopting it.
- What should happen when a cursor is malformed, stale, or used with a different sort?
- Reject it with a clean JSON:API 400 error object, not a 500. When the requested sort differs from the sort embedded in the cursor, invalidate or reject the cursor rather than returning inconsistent data. Your application owns this validation because the package cannot know each endpoint's sort contract.
- Is laravel-json-api/cursor-pagination safe to use in production?
- Treat provenance as the main risk: it has three stars, zero dependents, and a single maintainer, so there is little field validation or community-reported edge-case coverage. Assign a named internal owner, add characterization tests per endpoint, and pull Security into review for cursor tampering. Base64-encoded sort values can be forged to probe outside an authorized filter set, so make tamper-evidence a go/no-go gate.
- How should we maintain a single-maintainer pagination package long term?
- There is no upstream SLA or security-response process, so treat the package as adopted source rather than a normal dependency. Fork it under an internal namespace if needed, add a CI job against the parent framework's next minor, and name an internal owner. Keep the work scoped to how you paginate the JSON:API surface you already have.
Weaver
How can I help you explore Laravel packages today?