Query Filter Laravel Package

Product Decisions This Supports

• Build vs. buy for query/filter layers. Every product surface that exposes list endpoints — admin tables, customer dashboards, partner/public APIs — needs filtering, sorting, and pagination. This package is a "buy" (adopt) option for that layer, letting the team skip building a bespoke request-to-Eloquent translation layer with allow-listing, parameter validation, and sort whitelisting.
• API roadmap sequencing. If the roadmap includes public or partner-facing APIs, a declarative filter layer is a prerequisite for shipping consistent, documented query semantics (?filter[status]=active&sort=-created_at) without hand-rolling parsing per endpoint.
• Framework upgrade planning. v3.4.0 adds Laravel 13 compatibility. This is a signal, not a feature: the package is tracking upstream Laravel releases, so it can be counted as a non-blocker in an upcoming framework upgrade rather than a migration risk to budget for.
• Use cases that fit well: internal admin/back-office list views, CRUD APIs where clients need to narrow result sets, reporting endpoints with a bounded set of filterable columns, and multi-tenant dashboards where filters must be constrained to safe, indexed columns.
• Use cases that do not fit: search relevance, faceted discovery, fuzzy matching, or analytics-style aggregation — those are search-infrastructure decisions (Scout + Meilisearch/OpenSearch, warehouse queries), not query-parameter filtering.
• Risk/ownership decision. Adopting introduces a third-party dependency into the read path of most list endpoints — the highest-traffic code path in most applications. The v3.4.0 release provides weak but positive evidence of maintenance; it does not by itself justify adoption. Treat maintenance cadence, test coverage, and security posture of the allow-listing as the deciding factors.

When to Consider This Package

Consider adopting when:

• The application is on a currently supported Laravel version, and Laravel 13 compatibility matters to your upgrade timeline (v3.4.0 explicitly covers this).
• You have (or expect) more than a handful of list endpoints and are otherwise duplicating filter/parse/sort logic across controllers.
• Your filtering needs are bounded and column-based: equality, comparison, "in" sets, date ranges, relationship existence — the kind of thing you would otherwise express as a chain of when() clauses.
• Security posture matters: you want an explicit allow-list model so clients cannot filter or sort on arbitrary columns (a common source of data leakage and unindexed-scan incidents).
• You want convention over configuration — a single, uniform query grammar across endpoints and teams, easy to document for API consumers.
• Team size or timeline favors adopting a small, focused dependency over owning and maintaining an internal abstraction.

Look elsewhere when:

• You need full-text search, relevance ranking, typo tolerance, or faceting — pair this with a search engine or replace it entirely.
• Your query layer must support complex aggregations, computed/derived columns, or cross-model reporting that a filter allow-list cannot express cleanly.
• You require a dependency with a formal support window, security disclosure process, or vendor backing. A single-maintainer package (as the release metadata suggests) should be evaluated against your supply-chain policy.
• Your filtering rules are highly dynamic or per-tenant-schema-driven, such that a static allow-list becomes more configuration than code.
• You already have a well-tested internal filter layer — replacing working code carries migration cost with little product upside.
• Before committing, verify: the supported Laravel version range in composer.json, test suite coverage and CI status, release cadence over the past 12–18 months, how allow-listing failures behave (fail-closed vs. fail-open), and whether invalid parameters return 4xx or silently ignored input. v3.4.0 is a compatibility-only release — no behavioral change — so it does not resolve any of these questions.

How to Pitch It (Stakeholders)

For executives (one paragraph): We currently hand-build filtering and sorting for every list screen and API endpoint. This package replaces that repeated work with a small, focused library that enforces a safe allow-list, so clients can only filter on columns we've approved — reducing both engineering time and a class of data-exposure bugs. The new v3.4.0 release adds Laravel 13 compatibility, which means adopting it will not create friction in our next framework upgrade. It is a small dependency, not a platform commitment, and it does not change our product surface — it reduces the cost of building surfaces we've already planned.

For engineering (talking points):

• Scope is narrow by design: request query string → Eloquent query builder. It is not a search engine and does not attempt to be.
• Default-deny allow-listing is the core value: no filtering or sorting on unlisted columns, which removes the "arbitrary column in ?sort=" failure mode.
• v3.4.0 is compatibility-only — Laravel 13 support, no new features, no breaking changes. Low-risk upgrade; no behavioral retest beyond a standard smoke pass on list endpoints.
• Integration cost is per-endpoint and incremental; we can pilot on one non-critical admin resource before rolling it across API surfaces.
• Open questions to close in the pilot: response for invalid filter keys (4xx vs. silent), behavior on unindexed columns, test coverage and CI signal, maintainer responsiveness, and whether the supported Laravel range in composer.json matches our target version.
• Exit cost is low: filtering is a thin, well-bounded layer. If we outgrow it, the allow-list definitions translate directly to a custom implementation or a search-backed alternative.