Filter Laravel Package

Technical Evaluation

Architecture fit. The package is a thin, Laravel-native convenience layer: a trait on Eloquent models plus an abstract filter class that resolves query-string parameters into filterBy* methods on the query builder. It slots into the standard Laravel request → controller → Eloquent path with no new infrastructure, no external service, and no datastore assumptions. The trade-off is architectural: it moves HTTP input interpretation into the persistence layer. Applications already using query objects, repositories, or a specification pattern will find it competes with existing abstractions rather than composing with them. For CRUD-heavy admin surfaces and read APIs with a bounded, well-understood set of filterable fields, it removes a meaningful amount of boilerplate. For CQRS, event-sourced, or multi-datastore systems, it is a poor fit. Release 4.5.6 does not touch this calculus — it is a framework-compatibility change only, no new abstraction, no API surface change.

Integration feasibility. Low effort to prove out: composer require, publish config, add the trait, define one filter class, hit an endpoint. A spike is measured in hours, not days. The real feasibility question is not "can we wire it up" but "can we constrain it," and that is a design decision we make, not one the package makes for us. 4.5.6 widens the supported framework range to include Laravel 13.x, which removes a previously plausible blocker if our roadmap has us crossing that boundary within the package's useful life.

Technical risk.

• Input surface / allowlisting. The value proposition is dynamic dispatch from query strings onto model methods. Without an explicit allowlist and request-level validation, we are exposing whatever filter methods exist to whoever can craft a query string. This is the single largest risk and must be mitigated at the application boundary, not trusted to the package.
• Convention-over-configuration opacity. Filter resolution by naming convention is weakly visible to static analysis and IDEs. Renaming a filter method can silently change behavior (parameter ignored or exception) with no compile-time signal.
• Query performance. Composability is the feature and the hazard: unbounded filter/sort combinations against unindexed columns, deep offset pagination, and count(*) on large result sets. The package provides no guardrails.
• Bus factor and ecosystem validation. Single-maintainer project; dependents: 0 means no downstream package depends on it, so there is no transitive validation and no ecosystem pressure hardening edge cases. That is not disqualifying — MIT license means we can fork and vendor — but it shifts long-term ownership risk onto us.
• Version drift. Rapid release cadence (latest 2026-02-27) is a positive signal for activity but raises the probability of behavior changes in minor versions. 4.5.6 sharpens this rather than resolving it: a new Laravel major support claim shipped inside a patch release. That is good for adopters (no breaking-version jump required to get Laravel 13 support) but it means the composer constraint is a moving target and that "patch" no longer implies "no environment-affecting change." It also raises a diligence question we cannot answer from release notes alone: whether 4.5.6 actually runs CI against Laravel 13 or merely widened the constraint and hoped.
• Support-window asymmetry (new). Now that the matrix spans Laravel 13.x alongside older majors, the maintainer is carrying a wider compatibility surface as a solo operator. Breadth of declared support is not the same as depth of tested support; the risk of an untested combination silently breaking shifts to whichever of those versions we happen to run.

Key questions.

1. Does the package expose a first-class allowlist, or must we build one around it?
2. How are relation filters resolved — joins or lazy loading — and what is the N+1 profile?
3. What is the supported Laravel/PHP version matrix and the maintainer's stated deprecation policy? Partially answered by 4.5.6: Laravel 13.x is now declared supported, so the upper bound is current. Still open: the lower bound (how far back it supports), the PHP constraint, and whether CI actually exercises each supported Laravel major or only the newest. Deprecation policy remains undocumented.
4. Can filter logic be unit-tested without an HTTP request?
5. What is our escape hatch if upstream stalls — how much of our code touches the package directly?
6. Are we already using another query-param DSL (Scout, Spatie Query Builder)? Two DSLs in one API is a governance failure waiting to happen.
7. New: does upgrading to 4.5.6 change resolution behavior anywhere within our currently supported Laravel major, or is it strictly additive constraint widening? Confirm against our contract tests, not the changelog.

Integration Approach

Stack fit. Strong for a conventional Laravel monolith or modular monolith on Eloquent, especially where the API contract is "query params map to filters" (filter[status]=active&sort=-created_at). Weak where the query surface is small and stable enough that hand-written scopes are cheaper than a framework, or where multiple teams own different query semantics and need a shared, schema-validated contract. The framework-version spread now supported means fit is less contingent on where we sit in the Laravel upgrade cycle — the package is unlikely to be the thing that pins us to an older major.

Migration path. Do not adopt it as an architectural decision; adopt it as an adapter. Concretely:

1. Keep native Eloquent local scopes as the canonical implementation of each filter.
2. Have the package's filter classes delegate to those scopes. The package becomes the HTTP-to-query translation layer, not the home of business logic.
3. Pilot on one internal, low-risk read endpoint (admin list view) behind a feature flag, with shadow-mode comparison against the existing implementation for a release cycle.
4. Expand to additional internal endpoints, then to public read APIs only after the allowlist and validation contract are proven.

This keeps the swap cost to "replace the adapter" rather than "rewrite the query layer," which is the correct posture given the maintenance risk. The adapter posture also absorbs the 4.5.x cadence: a patch that only widens framework support is a no-op for us, and a patch that changes resolution behavior is contained to code we already own and test.

Compatibility. Verify PHP constraint against runtime, Laravel major version support (13.x now declared; confirm our current major is still inside the supported range and that the lower bound is not about to be dropped), and static analysis behavior (Larastan against dynamically resolved methods will need baselines or stubs). For 4.5.6 specifically: confirm whether the release widened the composer constraint only or also added Laravel 13 to the CI matrix — the former is a claim, the latter is evidence, and we should weight them differently in the ADR. If we are not yet on Laravel 13, treat 4.5.6 as a low-urgency patch: schedule it on our cadence, not upstream's, and gate it on our existing contract tests passing unchanged. Check for namespace collisions with existing traits and for conflicts with any search/scout integration. Confirm the config file publishes cleanly and that per-environment configuration is possible.

Sequencing.

1. ADR documenting the decision, the bounded context (read endpoints only), and the exit criteria. Record the supported framework range as of adoption, not "latest."
2. Build the allowlist + request validation contract first — this is a prerequisite, not a follow-up.
3. Pilot endpoint behind a flag with contract tests and a query-performance baseline.
4. Publish internal conventions: naming, one filter class per resource, index-review checklist per new filter.
5. Roll out to remaining internal surfaces; document when not to use it.
6. Deprecate overlapping ad-hoc query-param handling.
7. Added: pin the version explicitly and treat every upstream release — including patches — as requiring a changelog read before merge.

Operational Impact

Maintenance. Small dependency footprint, MIT licensed, so worst case we fork and carry it — a bounded, contained cost. The 4.5.6 release is a mild positive on maintenance: a solo maintainer shipping same-week support for a new Laravel major is the behaviour you want from a dependency you cannot influence. Budget for: pinning the version, upgrading on our cadence rather than upstream's, and reviewing filter classes in code review the same way we review migrations. The growing maintenance surface is not the package; it is the accumulated filter classes, each of which is a small piece of API contract with an implicit index requirement. Add one line to the maintenance checklist: read every upstream changelog, including patches, because framework-support changes have shipped in patch versions.

Support. Day-to-day support burden is developer-facing: conventions, examples, and "why isn't my filter firing" questions. Production support burden is different in kind — incidents will present as slow endpoints or 500s on malformed parameter shapes, and tracing those back to a specific filter requires query logging and an ability to disable a filter fast. We need a runbook entry: how to disable a filter via config without a deploy, and how to correlate a slow query to a filter class. Nothing in 4.5.6 changes the support profile.

Scaling. Application tier scales horizontally without issue; the database is the constraint. Every filter is a potential WHERE/ORDER BY against a column that may not be indexed, and the combinatorial space of filter combinations means index planning must be driven by observed query patterns, not by the filter list. Mitigations: per-endpoint maximum filter count, statement timeouts, keyset pagination for large result sets, read replicas or caching for hot filter combinations, and an index review gate on every new filter PR.

Failure modes.

• Renamed or removed filter method → silent no-op or runtime exception depending on configuration.
• Unvalidated parameter shape (arrays, nested keys) → 500s or unexpectedly broad queries.
• Relation filters → N+1 or cartesian joins under load.
• Unindexed sort/filter combination → full-table scan that passes in staging and degrades in production.
• Minor- or patch-version upgrade changing resolution behavior → subtle contract drift caught only by consumer complaints. 4.5.6 is a reminder that the patch channel is not inert here.
• Framework-major coupling → an upgrade we initiate on our schedule forces a dependency upgrade on upstream's schedule. 4.5.6 reduces this specific exposure for Laravel 13; it does not eliminate it for 14.
• Package abandonment → mitigated by fork, but only if we have kept the blast radius small.

Ramp-up. A Laravel-competent engineer is productive in roughly half a day. Establishing the allowlist, validation contract, test patterns, and observability is closer to one sprint of one engineer's time. The adoption cost is genuinely low; the governance cost is the real investment, and it should be scoped and owned explicitly rather than absorbed implicitly by whoever writes the first filter. 4.5.6 adds no ramp-up cost — it is a constraint change, not a behavioural one.