Lampager Laravel Laravel Package

Technical Evaluation

Architecture fit Lampager-Laravel is a thin adapter that layers keyset/cursor pagination onto Laravel's query builder and Eloquent. It owns no persistence, no schema, no transport, and no background process — it only shapes the WHERE/ORDER BY clauses of a read query. That makes it architecturally low-impact: it slots into the read path of list endpoints without altering application structure. It is a strong fit for large, append-heavy tables where OFFSET degrades (feeds, activity logs, exports, sync endpoints). It is a poor fit where the product contract requires random page access, total counts, or jump-to-page navigation.

Integration feasibility Installation is composer-only: no migrations, no publishable config, no service provider obligations, no queue workers. The primary integration decision is the version constraint, and v0.6.1 changes exactly that surface. Feasibility is high; the work is in validating the constraint against our actual framework minor rather than trusting it.

Technical risk

• 0.x semver. Minor releases may carry breaking changes. v0.6.1 is a patch and is itself low risk, but the package does not yet offer a stability guarantee.
• Proactive Laravel 14 allowance. This is the most consequential line in the release. Widening an illuminate/* constraint to a framework major nobody has run means Composer will resolve this package cleanly onto Laravel 14 and the failure, if any, surfaces at runtime or at framework-upgrade time — not at install time. Constraint widening is not the same as tested support.
• ResourceTest fix for Laravel 11+. The test suite was apparently red or unexercised against Laravel 11/12 until now. Functional code was likely fine, but it means "green CI" has not been a reliable signal for recent framework versions. Confirm whether this was a test-harness artifact or a real behavioural difference.
• PHP 8.5 support. Very new runtime. Unclear whether this is a CI matrix entry or a composer.json constraint bump.
• Bus factor of one. Single maintainer (@mpyw), community-supported, no vendor SLA.

Key questions

1. What is the actual CI matrix — which PHP × Laravel combinations are executed, versus merely permitted by composer.json?
2. Was v0.6.0 broken at runtime on Laravel 11/12, or only in the test suite?
3. Is the Laravel 14 allowance a bounded constraint or effectively open-ended? What is the support policy behind it?
4. Is there a roadmap to 1.0 with an explicit stability commitment?
5. Are there co-maintainers or a documented security/CVE process?
6. Do cursor tokens encode only sort keys, or is there any tenant/authorization scoping risk?

Integration Approach

Stack fit Laravel 10–12 applications using Eloquent or the query builder. Fits list endpoints behind infinite scroll, activity feeds, exports, and delta-sync APIs. Does not fit admin tables that need page numbers and record counts.

Migration path Moving from paginate()/simplePaginate() to keyset pagination requires three things beyond the library itself:

• A deterministic, unique sort key — add a tiebreaker (created_at, id) if the current sort column is not unique.
• A composite index that matches the ORDER BY exactly.
• A client-contract change: cursor token instead of page number, no total, no random access. This is an API version bump or a negotiated client change, and it is the dominant cost — not the server-side swap.

Compatibility Pin ^0.6.1 with a committed lockfile. Treat composer update as a reviewed change, specifically to prevent an unattended float onto an untested Laravel major. Validate against our real framework minor with a smoke test in staging rather than relying on the constraint.

Sequencing

1. Spike on one non-critical list endpoint behind a feature flag.
2. Add and verify the composite index; compare EXPLAIN against the current offset query.
3. Dual-run offset and keyset paths and diff result sets for a defined soak period to catch boundary duplicates/skips.
4. Migrate the client contract on that one endpoint.
5. Roll out endpoint by endpoint, largest tables first.
6. Re-evaluate at the next 0.x minor or 1.0.

Operational Impact

Maintenance Near zero runtime maintenance — no state, no daemon, no schema. The burden is dependency hygiene: track release cadence, review minor bumps, keep the lockfile authoritative. Realistically 1–2 hours per quarter.

Support Community, GitHub issues, single maintainer, no SLA. Acceptable for a non-differentiating utility. Becomes a real risk if it spreads across the whole API surface. Mitigation: wrap call sites behind an in-house pagination interface so the library is replaceable in a contained change.

Scaling This is the adoption rationale. Keyset pagination is an index seek rather than an offset scan, so deep-page latency stays flat as tables grow. Benefit scales with table size and page depth; near-zero on small tables where offset was already adequate. The index added to support it also typically improves the underlying list query.

Failure modes

• Missing or non-unique tiebreaker → duplicate or skipped rows at page boundaries. Silent, intermittent, hard to reproduce.
• Index not matching the ORDER BY → full scan, measurably worse than the offset query it replaced.
• Cursor contents leaking across tenants or authorization scopes if cursors encode only sort keys.
• A future framework upgrade resolving cleanly onto an untested Laravel 14 and failing at runtime.
• A 0.x minor landing with a breaking change mid-sprint.

Ramp-up Low. The API is small and reads like the framework's own paginator; a mid-level Laravel developer is productive in half a day. The learning curve is conceptual — keyset semantics, cursor opacity, the absence of random access and totals — and it sits mostly on the client and API-contract side, not the server team.

Assessment of v0.6.1 specifically No breaking changes, no new features, no deprecations. This is a signal release, not a capability release: it tells us the maintainer is actively tracking framework and runtime versions, and that the suite is only now green against Laravel 11+. It warrants adopting the package for a bounded use case with a pinned version and an abstraction seam — not a blanket endorsement, and not a reason to loosen our own constraint policy.