Laravel Query Builder Laravel Package

Product Decisions This Supports

• List/search endpoint delivery. Every product surface with a table — admin consoles, customer dashboards, public API collections — eventually needs filtering, sorting, field selection and pagination driven by the URL. This package makes that a configuration problem rather than a bespoke-code problem, which is the single biggest lever on how fast those screens ship.
• Build vs. buy for the query layer. The alternative is hand-rolling a RequestFilter/QueryFilter base class in-house. That is a two-to-five-day build plus permanent ownership of edge cases (invalid sort keys, unknown filter names, injection via ?sort=, pagination caps). Using a package converts that into a dependency review — cheap, and reversible if encapsulated.
• API contract standardization. If several teams expose collection endpoints, a shared query-parameter grammar (filter[x]=, sort=-created_at, per_page=) is a product decision, not just a technical one: it's what your API docs, SDKs and partner integrations will be written against. Adopting one library is the cheapest way to enforce consistency.
• Roadmap sequencing for the API surface. Committing to a query-builder now unblocks the roadmap items that depend on it — saved views, shareable filtered URLs, export-with-current-filters — without those becoming separate mini-projects.
• Framework-upgrade roadmaps. The 3.4.0 release adds Laravel 13 and PHP 8.5 support ahead of those versions being our problem, which means this dependency no longer appears as a line item on a future Laravel upgrade plan. That is a roadmap de-risking outcome, not just a maintenance nicety.
• Scope boundary on "search." This is a query shaping tool, not a search engine. It solves "filter the collection I already have," not "find the most relevant results." Keeping that line explicit prevents the roadmap from over-promising relevance ranking that this dependency cannot deliver.
• Not supported: relevance tuning, faceting, analytics-style aggregation, or anything requiring a search index. Those are Scout/Meilisearch/Elasticsearch decisions and should be evaluated separately.

When to Consider This Package

Consider it when all of the following hold:

• You need request-driven filtering/sorting/pagination on Eloquent models, and you want it declaratively (an allow-list of filterable and sortable fields) rather than via ad-hoc controller code.
• The team is small enough that a thin, low-ceremony library is preferable to a framework-scale one, and you are comfortable reading the source if documentation is thin.
• The Laravel and PHP version constraints match your stack, and you can verify that against your actual composer.json — not the README. As of 3.4.0 the package declares support for Laravel 13 and PHP 8.5, plus PHPUnit 12, so it is unlikely to be the constraint that blocks a stack upgrade.
• Maintenance cadence looks alive. The 3.4.0 release is current and is the strongest positive signal in the whole assessment: it lands forward-compatibility work (Laravel 13, PHP 8.5) rather than only routine dependency churn.

Treat the following as blockers or strong cautions:

• Ecosystem validation is still effectively zero. Stars and dependents remain negligible, meaning no third party has publicly bet on it. There is no Stack Overflow corpus and no tutorial coverage. Assume a bus factor of one, and note that the 3.4.0 release is mostly automated dependency bumps (Dependabot, license year, testbench constraint) — the maintainer is active, but the project still has one human in it.
• The problem is already solved by a market leader. The category is crowded: spatie/laravel-query-builder is the default answer with a large user base, documentation and a track record. Choosing this package requires a specific, articulable reason the incumbent does not fit — not merely "it's smaller." Note that the API surface here closely mirrors the incumbent's; confirm during the spike whether it is a fork/tracking implementation, because if so, switching cost in either direction is low and the encapsulation argument below becomes very cheap insurance.
• Long-lived, high-traffic public APIs. If the endpoint is a contractual surface you must support for years, prefer the dependency with the larger community. Framework-version support in 3.4.0 does not change this — it is evidence about one maintainer's diligence, not about the package's long-term survival.
• Teams with no appetite for encapsulation. The 3.4.0 signals reduce adoption risk but do not eliminate it. If you cannot commit to the adapter described below, use the incumbent.

Look elsewhere if: you need search relevance (Scout), you need a full API specification/design layer (OpenAPI tooling), you want first-party support (Laravel's own resource/filter patterns), or your team's policy requires dependencies above a minimum adoption threshold — most enterprise dependency policies would flag near-zero dependents out of the gate, and 3.4.0 does not move that number.

Practical mitigation if adopted: wrap it behind an internal QueryBuilder interface or base repository so the library is a swappable implementation detail, pin the version in composer.json (^3.4), and add contract tests on your query-parameter grammar so a future migration is a swap, not a rewrite.

How to Pitch It (Stakeholders)

To executives (one paragraph). We have a recurring, low-differentiation engineering task: turning URL parameters into database queries for every list screen and API collection we ship. This MIT-licensed Laravel package handles that for us, worth roughly a few engineering days per surface and, more importantly, removing a class of recurring security bugs (unvalidated sort/filter input). The latest release keeps pace with current Laravel and PHP versions, so it won't become the reason we can't upgrade. The remaining cost is a dependency we don't control, so we'd isolate it behind our own interface. Recommendation: adopt tactically behind an abstraction, not as a platform standard.

To engineering leadership. It is a small, single-purpose library, actively released, MIT-licensed — low legal and cost risk. Release 3.4.0 is a genuine improvement to the risk profile: it adds Laravel 13 and PHP 8.5 support and PHPUnit 12 compatibility, which means the framework-upgrade scenario that most threatens single-maintainer dependencies has already been handled once. Treat that as one positive data point, not a cleared risk — the release is otherwise dependency bumps, and the project still reads as one maintainer with no third-party users. Ask for: a thin internal adapter, ^3.4 pinning, and contract tests on our query grammar. If the team cannot commit to that encapsulation, use the established package instead — the switching cost later will exceed the days saved now.

To the engineering team. Use it if it earns its place in a spike: build one representative endpoint (filters + multi-column sort + pagination + an injection attempt on ?sort=) and compare against the incumbent on lines of code and clarity. Also use the spike to confirm whether the API mirrors spatie/laravel-query-builder — if it does, migration in either direction is a small diff and the dependency choice is genuinely low-stakes once abstracted. Ship it only with an allow-list of filterable/sortable fields — never pass user input straight to the query builder — and a hard cap on per_page. If the spike doesn't show a clear win, the answer is the boring, well-documented option.