Api Query Builder Laravel Package

Product Decisions This Supports

• Build vs. buy on API query ergonomics. Turning ?filter[status]=active&sort=-created_at&include=customer into safe, validated Eloquent constraints is recurring, undifferentiated work on nearly every list surface we ship — admin tables, dashboards, exports, search screens, partner feeds. This package is the candidate "buy" answer: roughly a sprint of hand-rolled request parsing saved per surface, priced against a real ownership cost.
• Roadmap cost curve for a whole class of items. A uniform query grammar converts "add a filter" from endpoint code into an allowlist entry. That changes how fast we can iterate on list/search surfaces, and it lets us scope those items with a smaller estimate than bespoke per-endpoint parameters.
• API contract shape. The supported filters, sorts, and includes are the contract clients integrate against. Adopting this means choosing a thin grammar we define and document ourselves rather than inheriting a widely-known community convention — a product-visible commitment to our docs and to client onboarding effort.
• Support-load and onboarding estimates. A documented, consistent grammar shortens partner integration and reduces "the filter isn't working" tickets relative to bespoke query parameters per resource.
• Sequencing and risk appetite. It makes a clean pilot candidate: one internal list endpoint, feature-flagged, behind an explicit success checklist. The rollback lever is a config flip, not a hotfix.
• What it should not drive: pricing, positioning, or any differentiator. Treat adoption as reversible infrastructure, not a strategic bet.
• Concrete near-term use cases: internal admin user and audit tables, internal dashboards, prototypes, one pilot list endpoint behind a flag. Explicitly not the customer-facing public API as a first move.

When to Consider This Package

Consider it only when all of the following hold:

• The surface is small and internal. Simple filters, sorting, pagination, and a handful of relations on an admin tool, internal API, or prototype where a grammar regression is a ticket, not an incident.
• Laravel compatibility is proven, not assumed. Last release July 2023, 26 stars, zero dependents. Validate Laravel 11/12 and PHP 8.2+ on a throwaway branch before committing anything to the roadmap — the stale illuminate/* constraint is the likeliest discovery, and it means forking on day one.
• We have named an owner and budgeted for a fork. Single maintainer, stale cadence: the realistic plan is "we vendor and own this," not "upstream will fix it." Pin the exact version (1.2.*, never ^1.0) and write the ADR with a name on it.
• Deny-by-default is enforced by us, not assumed. Defaults are the security surface. We must confirm by hand whether a missing allowlist entry fails open or closed, and whether an allowlisted include can walk into relations we never intended to expose.
• We have an escape hatch budget. The moment a requirement isn't a plain column comparison (created_after, free-text q, status[in]=…), we append a hand-written scope rather than bending the parser. Three of those in a sprint means we stop and fork.
• Success is testable. Four checks: sort works, filter works, ?filter[password]=1 is rejected or ignored, ?include=orders eager-loads without N+1. If the third fails, stop.

Look elsewhere when:

• The API is public, customer-facing, or contractually governed. Zero dependents and a stale release are continuity and supply-chain risks we shouldn't put on an external contract.
• We need security responsiveness. This is request-parameter parsing sitting directly in front of the ORM; injection-adjacent surfaces need an accountable maintainer.
• We need advanced semantics: relationship filters, nested includes, sparse fieldsets, cursor pagination, strict deny-by-default out of the box.
• We need community or support leverage. No dependents, no Stack Overflow footprint; debugging cost is entirely ours, and we should plan for it in estimates.
• The default alternative is spatie/laravel-query-builder, which occupies the same slot with current Laravel support, an active maintainer, and a community. Do not migrate an existing Spatie shop to this — net-negative risk swap, no capability upside.

How to Pitch It (Stakeholders)

For executives. We pay a recurring, low-differentiation cost on every list screen and API surface: hand-writing filter, sort, and pagination logic endpoint by endpoint. This package would let us express those as configuration plus an explicit allowlist, compressing the cost of a whole class of roadmap items and shortening partner integration time. The tradeoff is ownership — the library is small, has one maintainer, and was last released in mid-2023, so adopting it means treating it as vendored code we maintain. Recommendation: a bounded pilot on one internal list endpoint behind a feature flag, with a named owner, a pinned version, and a documented fallback. Upside is measured in saved engineering weeks; downside is capped at reverting a flag. It doesn't touch pricing, positioning, or anything customer-visible.

For engineering. This is a thin, readable implementation of the pattern we'd otherwise rewrite: declarative filters mapped to Eloquent constraints, sort and direction handling, controlled eager loading, and a chainable call in the controller. It is not a framework and has no extension ecosystem — assume a fork the first time we need a non-trivial filter. Concrete asks before we merge anything: (1) validate Laravel/PHP compatibility on a throwaway branch; (2) verify by reading source whether the allowlist is deny-by-default and whether includes can traverse unintended relations; (3) keep allowlists on the model, not at call sites, so they're auditable in one place; (4) scope authorization before the builder runs, and force a deterministic tiebreaker on sorted pagination; (5) assert on generated SQL in tests, not just JSON; (6) write the query-grammar docs ourselves, per endpoint — that file is our client contract and our checklist when a column is added. The legitimate fallback outcome is vendoring the parsing/allowlisting pattern into our own code and dropping the dependency; that's a win, not a failed pilot.