Product Decisions This Supports
- Build vs. buy for the query-filter layer. Every CRUD/index endpoint we ship re-implements the same three things: read filters from the request, apply an allowlist, and fall back to sane defaults (default sort, default status, default page size). This package targets exactly that seam. The decision it informs is whether that ~100-line concern stays hand-rolled per project, moves to a shared internal trait, or gets pulled in as a dependency.
- Feature scoping for listing and dashboard surfaces. When a roadmap item is "filterable admin table" or "search with defaults," this package can compress the estimate. If it does the job, the feature cost is largely UI plus allowlist configuration rather than query-building.
- Speed-to-market on internal tools. The highest-value use case is low-stakes, internal-only surfaces: admin panels, back-office list views, ops dashboards. Defaults matter most there (users expect a sensible filtered view on load, not an unfiltered dump), and the blast radius of a thin dependency is small.
- Standardization decision. The strategic question is not "this package yes/no" but "do we standardize on one filtering convention across the product?" The realistic alternatives are
spatie/laravel-query-builder (large ecosystem, well-documented, heavier), a shared internal trait (full control, no maintenance surprise), or this package (small surface, near-zero adoption signal). This package is a candidate only in the third slot and only if we accept the ownership terms below.
- Tech-debt triage. If engineering already has ad-hoc filter logic duplicated across N controllers, this package is evidence for a consolidation ticket — even if the ticket's conclusion is "write our own 80-line trait."
When to Consider This Package
Adopt, or rather evaluate, when all of the following hold:
- The requirement is genuinely simple: scalar filters on a single Eloquent model, plus default values when a filter is absent. No relationship filtering, no nested boolean groups, no full-text search.
- The surface is internal or low-risk, so a regression is a support ticket rather than a customer-facing incident.
- The team is comfortable reading the source directly, because that is the primary documentation. There is no meaningful doc, test, or issue-tracker signal to lean on.
- You are willing to vendor or fork it into the repo and treat it as first-party code. With 2 stars, 0 dependents, a single release (2025-01-16), and an overall score of 0.01, the package has effectively no community validation and no bus factor beyond one author. Depending on it via Composer without a fork means an unmaintained transitive dependency in the critical path of every list endpoint.
Look elsewhere — or build the ~100-line trait in-house — when any of these apply:
- You need relationship/eager-load filtering, multi-tenant scoping, or nested conditionals. Reach for
spatie/laravel-query-builder or hand-rolled query objects.
- Security review matters. Query-string-to-column mapping is an injection and data-exposure risk; an unvetted package in this position needs a read of the allowlist implementation before it touches production.
- You need a support contract, CVE response, or LTS story. There is none here.
- Your team's velocity depends on documentation and examples rather than source reading.
- The filtering requirement is likely to grow. Migrating off a small unmaintained trait later is cheap; migrating off one that shaped your API's query syntax is not.
A reasonable PM-approved path: timebox a one-day spike, read the source, and if it fits, copy the trait in with attribution rather than adding a dependency. Zero ongoing supply-chain risk, same delivery speedup.
How to Pitch It (Stakeholders)
To executives: This is a small, low-cost lever on delivery speed for internal list and admin screens — the kind of work that eats days without showing up on a roadmap. Caveat stated plainly: the package is essentially unproven (2 stars, no downstream users, one release), so we are not adopting a vendor, we are borrowing a pattern. Recommended posture is to lift the logic into our own codebase, which gets the speedup with none of the long-term dependency risk. Cost: roughly one engineer-day. Upside: removes a recurring per-feature implementation from every CRUD surface.
To engineering: The package addresses a real duplication: request-to-query filter mapping with default fallbacks, which we currently re-write in every controller. Before adopting, read the source — specifically the filter allowlist and how defaults are resolved — because there is no documentation or test signal to trust. If it holds up, vendor it into the repo as an internal trait rather than requiring it via Composer; the maintenance surface is a single small file, and that keeps us off an unmaintained dependency. If we need relationship filtering or nested conditions now or soon, skip it and use spatie/laravel-query-builder so we don't paint ourselves into a narrower query syntax. Either way, the consolidation ticket is worth filing independent of this package.