Eloquent Query Dsl Laravel Package

Product Decisions This Supports

• Pagination strategy per endpoint. The new cursor input is a sibling of page and mutually exclusive with it, so each resource gets one explicit pagination mode instead of an ambiguous default. Page-based stays right for back-office tables and anything needing jump-to-page or total counts; cursor-based becomes viable for infinite-scroll feeds, activity streams, and high-volume lists where deep OFFSET degrades.
• Incremental rollout, not a migration project. DslInputMap supports custom cursor parameter names and the existing page-number API remains compatible, so cursor pagination can be introduced per endpoint behind a flag or new API version. That is a product bet we can stage and measure (latency, error rates, client adoption) rather than a big-bang change.
• Build vs buy. Cursor input validation, Illuminate cursor construction, and structured output are commodity plumbing; adopting a package here saves days of per-service reimplementation and keeps contracts consistent across teams. The parts that are genuinely ours — query execution, permissions, response envelope — stay in the application layer by design, so there is no meaningful lock-in on the decisions that matter.
• API contract clarity. Mutual exclusivity plus mode selection driven by raw input keys (not parser defaults) means an endpoint can't silently flip to page mode because a parser filled in a default. That is a correctness guarantee we can put in an API spec and defend in review.
• Support and debuggability. Bidirectional next / previous cursors and a directly debuggable position parameter reduce the cost of diagnosing customer pagination bugs — support and on-call can inspect cursor state instead of reverse-engineering opaque tokens.

When to Consider This Package

Consider it when:

• You are on PHP 8.0–8.3 and Illuminate 9–12 and already have, or plan to add, a query DSL layer across endpoints.
• You need a consistent pagination contract across multiple endpoints or teams, and want cursor pagination without breaking existing page-number clients.
• You want pagination input handling and cursor construction standardized while keeping execution, authorization, and response shapes owned by each application.

Look elsewhere when:

• You expect the package to execute paginated queries, enforce permissions, or shape responses. Its stated boundary excludes all three; if you need an end-to-end pagination solution, this is a component, not a solution.
• Your lists are small and simple, where framework-native pagination is sufficient and an extra abstraction is pure overhead.
• You require a stable 1.0 API contract. At 0.4.0 this is pre-1.0; pin the version and budget for minor-version churn.
• You are outside the supported PHP/Illuminate matrix.

How to Pitch It (Stakeholders)

For executives: a low-cost, low-risk capability addition. It lets us offer modern cursor pagination on high-traffic and real-time lists while keeping every existing page-number API working unchanged — no migration deadline and no breaking change for customers. Quality gates are green across the board (35 tests / 80 assertions, PHPStan level 8, code style, security audit, full CI matrix), and the dependency footprint is a small shared package, not a platform commitment.

For engineering: release 0.4.0 adds a structured cursor input mutually exclusive with page, bidirectional next / previous cursors, a debuggable position parameter, and configurable cursor parameter names via DslInputMap. QueryDsl::apply() now selects pagination mode from raw input keys, so parser defaults can no longer silently select page mode. The boundary is deliberate: the package validates cursor input, builds Illuminate cursors, and returns structured output; we keep query execution, authorization, and response structure. Small surface area, well-tested, and safe to adopt per endpoint. Recommend pinning to 0.4.x given the pre-1.0 version.