Filtereasy Laravel Package

Technical Evaluation

Architecture fit. gsferro/filtereasy is a thin, trait-based filtering layer that sits between the HTTP layer and the Eloquent query builder — it lets a model expose declarative filters driven by the request query string. Architecturally that places it at the most sensitive seam in a Laravel application: the point where untrusted input becomes a SQL predicate. It fits cleanly in a Laravel monolith or API service where list/index endpoints currently accumulate ad-hoc $request->has('status') conditionals, and it composes with API Resources and Form Requests rather than competing with them. It does not fit where filtering is already modeled explicitly (dedicated query objects, Spatie Query Builder, or hand-rolled scopes), because adopting it would mean re-opening stable endpoints for marginal gain.

Integration feasibility. Mechanically low-cost: composer require, package auto-discovery, publish config, apply the trait to a model, add filter classes. A credible pilot is 1–2 engineer-days. The effort is not in wiring — it is in the guardrails we would have to build around it.

Technical risk. The adoption signals are the dominant risk: 1 star, 0 dependents, a single maintainer, and a last release in October 2024. This is effectively unvetted third-party code operating on the query builder. Specific risks to retire before any production use:

• Identifier injection — whether user-supplied keys can reach column/table identifiers, or are constrained to an explicit allowlist.
• Authorization bypass — whether filters can target fields a caller should not see or filter on (email, tenant ID, soft-delete flags, internal status).
• Framework drift — whether composer constraints cover the Laravel/PHP versions we run, and whether semver is actually honored.
• Resolution behavior — if filter classes are resolved by naming convention from request input, that is a class-instantiation surface we must verify.
• Abandonment — bus factor of one, with no security policy or disclosure process visible.

Key questions.

1. Does the package enforce an explicit allowlist of filterable fields, or does it derive them from input?
2. How are filter classes resolved — config map, convention, or container? Can input influence resolution?
3. What are the composer.json constraints for laravel/framework and php, and is there CI across supported versions?
4. What happens on malformed/unknown filters — validation error, exception, or silent no-op?
5. Is there a test suite we can run against our own Laravel version, and what is its coverage of edge cases?
6. Is there any rate/complexity limit on filter combinations, or can a caller compose an unbounded query?

Recommendation: conditional approval, scoped to internal, read-only, low-PII list endpoints. Not approved for customer-facing or tenant-scoped data until forked and hardened.

Integration Approach

Stack fit. Laravel + Eloquent, MySQL/Postgres. No infrastructure requirements, no queue or cache dependency, no external service — which is the package's main operational virtue. Confirm framework constraints first; if it lags our Laravel major, that alone closes the evaluation.

Migration path. Incremental and endpoint-by-endpoint, not a sweep. Two entry scenarios:

• Greenfield endpoints — adopt directly behind our wrapper from day one.
• Existing filter code — replace one endpoint at a time, keeping the old code path behind a feature flag until contract tests pass on the new one.

Compatibility. Pin an exact version (not a caret range), commit the lockfile, and vendor or fork the source into our internal VCS. Run our own integration tests against it rather than trusting upstream CI. Treat any upstream release as a change requiring review, not an automatic bump.

Sequencing.

1. Read the code (1 day). Full source review against the key questions above; record findings as pass/fail on identifier injection and allowlist enforcement.
2. Compat spike (0.5 day). Install in a scratch Laravel app at our target version; verify discovery, config publish, and a smoke filter.
3. Pilot (2 days). One internal admin list endpoint with non-sensitive data. Instrument query time and error rate.
4. Harden (3 days). Wrap the package behind our own Filterable trait/facade so the dependency is one swap point; enforce a per-model allowed-fields config; normalize error handling to 422 instead of 500; add contract tests.
5. Fork (1 day). If the pilot holds, fork to internal namespace and publish to our private registry. This is the decision gate — forking is cheaper than an incident.
6. Expand (ongoing). Roll to customer-facing endpoints only with explicit authz checks per filter and a query-cost ceiling.
7. Decommission legacy. Remove the ad-hoc filtering branches once parity is proven.

Operational Impact

Maintenance. We own this package the moment it touches production. Budget roughly 1–2 engineer-days per quarter for fork upkeep plus a defined slice of every Laravel major upgrade. Single maintainer means upstream is a convenience, not a support channel.

Support. MIT license, no vendor, no SLA, no disclosed security process. Ownership must be explicitly assigned to the platform/backend team, with a named individual responsible for monitoring upstream activity and applying patches. Without that assignment, the fork rots silently.

Scaling. The package itself does not scale — the database does. Filtering moves work into WHERE clauses, so the binding constraint becomes index coverage on filterable columns and the number of filter combinations a client can chain. Two mitigations belong in the hardening step: a hard page-size cap and a statement/query timeout, plus composite indexes on the field sets we actually expose. Watch for filters on unindexed or low-cardinality columns producing full scans under load.

Failure modes.

• Malformed or unknown filter input throws → 500s in production unless caught and mapped to 422.
• Filter on a non-existent or renamed column → SQL error surfaced to the client.
• Convention-based class resolution → unintended class instantiation if input can influence it.
• Upstream minor release with breaking changes → silent behavior shift on composer update.
• Upstream abandonment → no patches for a Laravel incompatibility or a reported injection issue.
• Unbounded filter composition → slow queries and connection pool pressure under concurrent load.

Ramp-up. Low for anyone fluent in Eloquent — half a day to first working filter. The offsetting cost is documentation: upstream docs are thin at this adoption level, so we must publish an internal usage guide and, critically, an approved-fields checklist that reviewers enforce at PR time. That checklist is the primary control that keeps the package's flexibility from becoming an information-disclosure vector.