Laravel Query Strategies Laravel Package

Product Decisions This Supports

• Feature work: Shipping filterable, sortable, field-selectable list endpoints (admin tables, ops dashboards, reporting grids, customer search pages) without writing bespoke query-translation code per resource. The release covers the concrete primitives PMs usually have to schedule as custom work: field selection, relationship filtering, nested relationship sorting, aggregate includes (withCount/withSum), soft-delete visibility via TrashedClause, range filters via BetweenClause, null checks, and model scopes via ScopeClause.
• Roadmap velocity: Adding a new filterable resource becomes configuration plus allowlisting rather than a new controller/filter class — default model strategy with auto-pickup and default filters reduce per-resource boilerplate, which directly affects how many resources we can onboard per sprint.
• Build vs buy: This replaces a homegrown filter DSL / QueryBuilder facade. It is OSS with no licensing cost; the trade is dependency risk on a single-maintainer package and coupling to Laravel's release cadence.
• Security posture: Opt-in strict mode plus eager-load relationship validation makes allowlisting a first-class decision — we can choose server-defined filters only, or safely expose a constrained query surface to trusted clients, rather than betting on ad-hoc sanitisation.
• Quality / SLOs: Eager-load validation, the removal of a redundant limit before paginate, and the cached defaultMethods map support page-load performance goals and reduce N+1 and over-fetching risk in list views.
• Platform consistency: One query-parameter contract across all resources means front-end data grids (TanStack, AG Grid, Filament-style tables) integrate the same way everywhere.

When to Consider This Package

Consider it when:

• You have, or expect to have, multiple list endpoints with user-driven filter/sort/field-selection behaviour; the value scales with resource count.
• You want a consistent query-parameter contract across models rather than per-controller implementations.
• You need soft-delete-aware filtering, model scopes, null/range clauses, and relationship filtering as standard rather than as tickets.
• You are on Laravel 13 with a modern PHP version — 13.0.0 tracks Laravel 13 and Testbench 11, and the Parameter object is now readonly.
• You treat static analysis and tests as adoption signals; Larastan level 8 plus expanded test coverage is a meaningful maintainability indicator.
• Reducing injection/mass-assignment blast radius via allowlisting (strict mode) matters to your threat model.

Look elsewhere when:

• You only need one or two trivial filters; the abstraction and learning curve won't pay back.
• You need a general query language (GraphQL, full JSON:API sparse-fieldset fidelity) or an analytics/SQL reporting layer — this is not that.
• You cannot align to Laravel 13 yet; check the package's backward-compatibility cadence before committing.
• You require vendor SLAs or enterprise support; this is single-maintainer OSS.
• The team is not Eloquent-fluent — the abstractions assume Laravel conventions.

How to Pitch It (Stakeholders)

Executives: This is an open-source building block that lets us ship flexible, self-serve filtering and sorting on our internal tools and customer-facing lists with substantially less engineering effort and a smaller bug surface. It makes each new admin or reporting screen cheaper than the last and is safer by default because filters are allowlisted. The cost is a dependency and an upgrade cadence, not a licence.

Engineering: 13.0.0 is a maturity release, not a point patch. It adds Laravel 13 / Testbench 11 support; a declarative filter/clause/parameter model (ScopeClause, IsNull/IsNotNull, TrashedClause, BetweenClause, callback/inline filters); default model strategy with auto-pickup and default filters; aggregate relationship includes; nested relationship sorting; and opt-in strict mode with eager-load validation. Performance work (cached defaultMethods map, direct clause instantiation, removal of collect() in hot paths, redundant-limit fix) plus Rector modernization, readonly Parameter, and Larastan level 8 signal it is production-lean. Recommendation: timebox a spike on one internal list endpoint to validate DX, the strict-mode allowlist ergonomics, and the Laravel 13 upgrade path before standardising across resources.