Eloquent Query Dsl Laravel Package

Getting Started

• Install the package with Composer and confirm your app meets the supported matrix: PHP 8.0–8.3 and Illuminate/Laravel 9–12.
• Start by reading the QueryDsl and DslInputMap APIs. QueryDsl::apply() is the main entry point for normalizing raw request input into either page or cursor pagination mode. DslInputMap controls the public cursor parameter names.
• First use case: add dual-mode pagination to a listing endpoint. Accept either a traditional page input or a structured cursor input, pass the raw request keys into QueryDsl::apply(), then branch on the returned pagination mode to build your Eloquent query.
• Minimal controller shape:

$pagination = QueryDsl::apply($request->query());

// Branch on page vs cursor mode from the structured result,
// then apply ordering/scopes and execute the query yourself.

The package validates cursor input and constructs Illuminate cursor objects. Your application still owns query execution, authorization, and response formatting.

Implementation Patterns

• Enforce mutual exclusivity at the request-validation layer. A request should contain either page or cursor, never both. Return a clear 422 response if both are supplied.
• Keep existing page-based APIs unchanged. The 0.4.0 release preserves page pagination compatibility; continue passing the raw page key and let QueryDsl::apply() select page mode.
• For cursor mode, use the structured cursor input with next, previous, and position. Use next for forward navigation and previous for backward navigation. Treat position as a debugging aid rather than a primary client-facing pagination token.
• Configure DslInputMap when your public API uses different cursor parameter names, such as after/before. Keep validation rules, request docs, DslInputMap, and response metadata aligned.
• Typical workflow:
  1. Validate the request, including mutual exclusivity and cursor shape.
  2. Call QueryDsl::apply() with raw request input.
  3. Branch on page vs cursor mode.
  4. Apply authorization/scopes and a stable order to the query.
  5. Execute the query and return a consistent response envelope with mode-specific metadata.
• Suggested response shape:

{
  "data": [],
  "pagination": {
    "mode": "cursor",
    "cursor": {
      "next": "...",
      "previous": "...",
      "position": "..."
    }
  }
}

• Integration tip: keep cursor metadata opaque to clients except for position in debug environments. Do not change the page-mode response contract when adding cursor support.

Gotchas and Tips

• QueryDsl::apply() determines pagination mode only from the original raw input keys. Do not pass a DTO or merged defaults that always include page; that can accidentally force page mode even when the client sent a cursor. Pass $request->query() or a carefully filtered raw array.
• Do not rely on parser default values to decide pagination mode. Validate explicitly and avoid injecting page=1 before calling QueryDsl::apply().
• Cursor pagination requires stable, deterministic ordering. Ensure your query has a unique tie-breaker or otherwise stable sort; otherwise next/previous navigation can skip or duplicate records.
• The package does not execute paginated queries, enforce permissions, or define your response structure. Apply policies, scopes, and serialization in the application layer.
• If a cursor is not recognized, check DslInputMap first, then confirm the request uses the expected public parameter names. Use position to reproduce and debug cursor state.
• Test both directions: forward with next and backward with previous. Also test the mutual-exclusivity rule and custom cursor parameter names.
• Extension points include custom DslInputMap mappings and your own response serializer/query builder integration. Keep custom cursor names consistent across validation, QueryDsl::apply(), and response output.
• Although 0.4.0 reports PHPUnit, PHPStan level 8, code style, security audit, and CI matrix success, add application-level tests for your own request validation, ordering, authorization, and response contract.