Product Decisions This Supports
- Feature scoping for filtering/search. Decides whether "let users filter the orders list by status, date range, and customer" is a two-day story or a two-sprint epic. This package turns query-string parameters into Eloquent
where clauses, so the answer can be "two days."
- Build vs. buy. The capability is small and well-understood; the real decision is "adopt a free micro-package, adopt a larger mature library, or write ~200 lines in-house." This package is the cheap end of that spectrum and makes the in-house option easy to benchmark against.
- Roadmap allocation. Frees engineering from repetitive boilerplate on admin panels, internal dashboards, and MVP/partner endpoints, redirecting capacity to differentiators.
- API surface standardization. Forces an explicit decision on whether filtering syntax is consistent across all read endpoints — worth deciding once, before three teams invent three conventions.
- Use cases it unlocks quickly: internal admin/support tooling, back-office reporting views, prototype and MVP APIs with a known consumer set, data-export endpoints, and partner integrations with negotiated query contracts.
- Risk-acceptance decision. Given 10 stars, a single maintainer, and a January 2024 last release, adopting it is explicitly a "we can own this if it dies" decision — the PM should record that as an accepted risk, not let it slip through.
When to Consider This Package
Consider it when:
- You're on Laravel and need straightforward equality/range filtering on read endpoints this sprint.
- The consumers are internal, known, or contracted — admin UIs, internal tools, a handful of partners.
- Your organization's policy tolerates GPL-3.0. This is the single biggest gate. For a hosted SaaS with no distribution, GPL obligations are generally not triggered, but many companies have blanket copyleft bans in their dependency policy. Get legal's answer before the spike, not after.
- The codebase is small enough that forking or vendoring is realistic — with ~10 stars you should assume you are the maintainer of last resort.
- Data volumes are modest, or you're prepared to add indexes and query caps yourself.
Look elsewhere when:
- The API is public-facing and untrusted. Mapping arbitrary URL parameters onto query columns without a strict allowlist invites information disclosure (filtering on
password_reset_token-style columns) and cheap denial-of-service via pathological filter combos. You need whitelisting, complexity limits, and rate limiting regardless of which tool you pick.
- You also need sorting, pagination, relationship inclusion, or sparse fieldsets —
spatie/laravel-query-builder (MIT, actively maintained, large community) covers the whole family and is the obvious default for most teams.
- Your dependency policy requires permissive licensing, vendor support, or a documented security-response process.
- You're operating at scale where cursor pagination and index-aware filtering matter.
- You want a library with a community large enough that Stack Overflow answers exist.
Suggested evaluation: timebox a one-day spike on one internal endpoint, with exit criteria — does it cover your top five filter types, and can you wrap it in an allowlist without forking?
How to Pitch It (Stakeholders)
To executives: This is a small, free, open-source accelerator that can shave days off shipping filtered list views and dashboards — the kind of plumbing users expect but never thank us for. There's no license fee and no vendor contract. The trade-off is that it's a tiny project (10 stars, one maintainer), so we'd be taking on the maintenance risk ourselves. Recommendation: use it behind a timeboxed spike to validate, not as a long-term platform commitment, and revisit if we outgrow it.
To engineering: It's a simple convention for turning query-string parameters into Eloquent constraints — minimal surface area, easy to read, quick to drop in. Three caveats we should plan around: (1) it's GPL-3.0, so confirm with legal before it lands in composer.json; (2) it's effectively single-maintainer with a January 2024 release, so assume we may fork it — which is fine, it's small; (3) it doesn't protect you, so we wrap every exposed endpoint in an explicit column allowlist plus rate limiting. If we need sorting, pagination, and relation includes too, we should just take spatie/laravel-query-builder instead and skip the fork risk.