Laravel Query Strategies Laravel Package

Technical Evaluation

Architecture fit myerscode/laravel-query-strategies sits in the request-to-Eloquent seam of a Laravel API: HTTP query parameters are mapped to a declarative Strategy → Parameter → Clause pipeline that composes filters, sorts, includes, and pagination onto a query builder. This is architecturally attractive for teams operating many REST/JSON:API endpoints, because it centralises ad-hoc ->when($request->has(...)) logic into named, testable, reusable strategies. The 13.0.0 feature set materially broadens that fit: relationship filtering, nested relationship sorting, aggregate relationship includes, field selection, ScopeClause for model scopes, TrashedClause for soft deletes, and BetweenClause for ranges cover the majority of realistic list-endpoint requirements without bespoke code.

Integration feasibility Composer-installable with a conventional service-provider/config-publish flow. The release targets Laravel 13 and Testbench 11, which is the dominant feasibility gate — adoption is effectively tied to running Laravel 13 (or a narrow adjacent range). Test coverage improvements, Rector modernisation, and Larastan level 8 compliance are positive signals of engineering hygiene and reduce the "abandoned package" risk. The Parameter readonly conversion and StrategyManager instantiation fix indicate internal contracts were tightened, which is good for stability but hostile to anyone who extended internals.

Technical risk This is a 0-to-13.0.0 jump with no prior assessment, and a major version bump plus "update to Laravel 13" almost certainly signals dropped support for earlier Laravel/PHP versions and at least one breaking change for custom strategies/parameters. Specific risks: (1) Parameter being readonly breaks any code that mutates parameters post-construction; (2) the StrategyManager double-instantiation and "cached compiled defaultMethods map" changes can alter resolution order or side-effect timing for custom strategies; (3) the eager-load validation fix and strict-mode addition mean previously accepted (and silently ignored or exploited) input now behaves differently — a behavioural, not just API, break; (4) "filter shorthand for clause class" and callback/inline filters introduce user-adjacent dynamic query construction, so strict mode should be treated as a security control, not a convenience toggle. Overall risk is moderate: high blast radius if adopted as the primary query layer, but mitigable via staged rollout and strict mode.

Key questions

• What is the definitive breaking-change list between 12.x and 13.0.0, and is there an upgrade guide?
• What are the exact illuminate/* and PHP version constraints, and is there a maintenance branch for Laravel 11/12?
• Is opt-in strict mode allowlist-based, and what is the escape hatch (per-strategy overrides)?
• Are callback/inline filters designed for developer-authored closures only, or can they be reached from untrusted input?
• What is the bus factor and release cadence of the maintainer(s)?
• Is there a documented extension contract for custom clause classes given the readonly/refactor changes?

Integration Approach

Stack fit Strong fit for a Laravel 13 API-first application or a monolith with a public/partner API surface. Weaker fit where query semantics are highly bespoke, where the GraphQL/API-platform layer already owns filtering, or where a DBA-owned reporting layer expects raw SQL. The package's vocabulary (strategies, parameters, clauses) maps cleanly onto an API platform team's mental model and gives the TPM a legible artefact for API contracts — each strategy is effectively a documented, versionable endpoint specification.

Migration path Since there is no incumbent assessment, treat this as greenfield. Two lanes: (a) if the estate is already on Laravel 13, adopt 13.0.0 directly in a non-critical service and pin exactly (13.0.*) until the changelog has been read end-to-end; (b) if on Laravel 11/12, do not upgrade Laravel 13 to reach this package — instead identify the last 12.x tag, or defer adoption until the framework upgrade is independently justified. For teams that prototyped earlier versions, budget explicit rework for any custom Parameter subclasses (readonly) and any reliance on prior eager-load leniency.

Compatibility Requires Laravel 13 / Testbench 11 alignment and the PHP floor implied by the Rector modernisation (assume modern PHP; verify composer.json). Compatibility risk concentrates in third-party packages that pin older illuminate/support, and in any in-house traits that monkey-patch StrategyManager.

Sequencing

1. Spike: convert one representative list endpoint to a strategy; measure LOC removed and query count.
2. Define the strategy catalogue and naming conventions as the API contract, reviewed with the API consumers.
3. Enable strict mode in staging only; catalogue every rejected parameter to confirm no legitimate client traffic breaks.
4. Roll to one production endpoint behind a feature flag; observe latency and error rates for a full release cycle.
5. Expand endpoint-by-endpoint; retire legacy filter code as each endpoint migrates.
6. Only then consider adopting callback/inline filters, and gate them behind code review.

Operational Impact

Maintenance Low ongoing code maintenance (declarative config replaces repetitive controller logic) but non-trivial version maintenance: a package that jumps to a new major aligned with each Laravel major means a recurring, calendar-driven upgrade task. Recommend tracking releases and assigning an owner; pinning minor versions is essential. The Rector/Larastan work means formatting churn between versions is likely, so expect diff noise on upgrade.

Support Community/maintainer-driven, not vendor-backed. Acceptable for internal tooling; for a customer-facing API with SLAs, require either an internal fork capability or a documented fallback to hand-written query scopes. The level-8 static analysis and improved test coverage are reasonable proxies for supportability, but they are not a support contract.

Scaling Performance work in this release is directly relevant to scaling: caching the compiled defaultMethods map removes per-request reflection, direct clause instantiation and replacing collect() with array operations reduce allocation on hot list endpoints, and removing the redundant limit() before paginate() avoids a class of count/limit bugs. Net effect is favourable for high-QPS read endpoints, provided strict mode and eager-load validation are on — those are also the primary defence against clients constructing pathological queries (deep relationship includes, unbounded sorts).

Failure modes

• Permissive by default: without strict mode, unknown or unexpected parameters may be silently ignored or loosely interpreted, producing inconsistent API behaviour and a weak input-validation posture. Mitigation: strict mode on in all non-local environments.
• Relationship abuse: includes/sorts across relationships can produce expensive joins; the eager-load validation fix helps, but rate limiting and per-strategy include allowlists remain necessary.
• Extension breakage: custom clauses/parameters failing after refactors, surfacing as runtime resolution errors rather than compile-time failures. Mitigation: contract tests around every custom clause.
• Behavioural drift on upgrade: bug fixes that change accepted input are invisible in semver-major terms but visible to clients. Mitigation: replay production query logs against staging after each major.
• Single-maintainer risk: abandonment or slow CVE response. Mitigation: fork-and-vendor contingency.

Ramp-up Engineers familiar with Eloquent will onboard in roughly a sprint; the conceptual load is the three-layer vocabulary plus the strategy registration/config conventions, not the underlying ORM. The main ramp-up cost is organisational: agreeing the strategy catalogue, naming, and allowed-parameter policy is a design exercise that should be owned by the TPM/API owner, not left to individual endpoint authors. Budget documentation work for the strategy catalogue — it doubles as the public API contract and is the highest-leverage artefact for reducing support load.