Filter Laravel Package

Product Decisions This Supports

• Build vs. buy for list-endpoint plumbing. Every product surface with a collection view — admin tables, search results, activity feeds, public API GET /resources endpoints — needs the same thing: turn request parameters into constrained Eloquent queries. This package is a candidate "buy" (free, MIT) for that plumbing, so the decision becomes "do we spend engineering days on a filtering convention, or adopt/borrow one?"
• Standardizing a filtering convention across teams. A dedicated filter-per-model structure forces a decision: is query filtering a first-class, reviewed artifact (explicit filter classes, whitelisted inputs) or an ad-hoc ->when($request->has(...)) chain scattered through controllers? That's an architecture/consistency decision with real maintenance-cost implications, not just a library choice.
• Scoping an API contract. Filterable fields are effectively part of your public API surface. Choosing an explicit-filter-class approach (vs. generic field mapping) makes the set of supported filters an enumerable, testable list — which supports API versioning, documentation, and deprecation planning decisions.
• Roadmap sequencing for internal tooling. For admin dashboards and internal ops views, filtering is table stakes and non-differentiating. This package supports a "ship the CRUD surface fast, invest differentiation elsewhere" roadmap call.
• Use cases where it fits: small, stable filter sets per model (status, date range, owner, search term); internal admin/ops tooling; teams already comfortable with Laravel traits and Eloquent scopes.

When to Consider This Package

Consider it when:

• You have a small, well-bounded set of filters per model and no near-term need for sorting, pagination, field selection, or relationship includes as part of the same abstraction.
• You want explicit filter classes (one per model, reviewed in PRs) rather than client-controlled, convention-derived field mapping — i.e., you value a tight, auditable allowlist.
• You're on a Laravel version this package actually supports, and you've confirmed the last commit / issue activity is compatible with your framework and PHP version. Verify this before anything else — at 21 stars this is a small community package, and version support is the most likely blocker.
• You treat it as a pattern to borrow rather than a dependency to inherit: read the source (it's small), vendor or reimplement the trait, and keep the API shape. That captures most of the value with none of the vendor risk.
• The cost of replacing it later is low — filters are localized, so the blast radius of a swap is small.

Look elsewhere when:

• You need sorting, pagination, sparse fieldsets, and relationship includes under one consistent, documented contract — spatie/laravel-query-builder is the mature default here, and tucker-eric/eloquentfilter covers the filter-class style with broader adoption.
• You need nested / relationship-aware filtering or complex boolean composition; a per-model class approach tends to get awkward fast.
• You're exposing filtering on a public, high-traffic API where input validation, DoS resistance (unbounded LIKE scans, expensive joins), and index-aware query shapes must be enforced deliberately.
• Maintenance risk is unacceptable for the component — e.g., it sits on a critical path with no internal owner. Low stars + unknown release cadence means you become the maintainer.
• Your codebase already has a filtering convention; a second one costs more than it saves.

How to Pitch It (Stakeholders)

One-liner: A small, MIT-licensed Laravel package that turns request parameters into Eloquent query constraints via explicit filter classes — useful, but low-adoption, so the recommendation is to adopt the pattern, not necessarily the dependency.

For executives: This is a low-cost, low-drama decision. The package is free and does undifferentiated work (list filtering) that we'd otherwise hand-roll. The risk isn't money, it's maintenance: at ~21 stars it has a thin community, so we should plan on owning any code we depend on. Net: adopt the approach to speed up admin/API list views, keep it isolated behind our own interface so it's swappable, and re-evaluate against the more established Spatie option if our filtering requirements grow past simple field constraints.

For engineering: Trait-based filter classes, one per model, giving an explicit and testable allowlist of filterable fields — good for API contract clarity and for keeping raw request data out of controllers. Trade-off: no built-in sorting/pagination/includes, limited community support, and version compatibility must be confirmed against our Laravel/PHP versions before adoption. Recommended path: timebox a spike, validate against two real endpoints, and if it holds, either pin the dependency with an internal wrapper or vendor the ~few hundred lines of source. Do not use it as the foundation for public API filtering without a review of query-shape and validation safety.