Laravel Eloquent Model Filter Laravel Package

Technical Evaluation

Architecture fit The package targets the read path: a model-level trait plus a per-model filter class that translates request query parameters into Eloquent where clauses. That maps cleanly onto a conventional Laravel layering (Controller → Service/Query Object → Eloquent) and is the same shape as the widely adopted tucker-eric/eloquentfilter pattern — this package appears to be an opinionated derivative of it. Architecturally it is a cross-cutting concern bolted onto the domain model, which is acceptable in Laravel but does mean persistence-layer code inherits HTTP-shaped input. For teams already using query objects or repository patterns, the value is marginal; for teams with fat controllers, it removes a real class of duplication.

Integration feasibility Low as a direct Composer dependency. The 2018-08-21 release predates Laravel 6 and PHP 8; expect constraints around illuminate/*: 5.5–5.7 and php: ^7.1. On Laravel 9+ Composer will refuse resolution without --ignore-platform-reqs, which is not an acceptable production posture (it disables the only safety net you have against transitive incompatibility). Feasibility is moderate-to-high as vendored source — the trait itself is likely 100–200 lines of where/whereLike/whereIn dispatch and is trivially portable.

Technical risk

• Abandonment is the dominant risk. There is no one to ship a fix, and no fork community to absorb one.
• Unvalidated input→column mapping. The core mechanic converts query-string keys into SQL column references. If the allowlist ($filterable or equivalent) is optional or permissive, you inherit an injection / information-disclosure surface (filtering on password_hash, enumerating via error-based probing). This must be verified before any exposure to untrusted traffic.
• Semantic drift from modern Eloquent. No awareness of whereBelongsTo, relationship aggregates, chaperone(), or strict-mode behaviors added in later Laravel versions; nested/relationship filtering is likely naive.
• Zero test signal. No dependents means no downstream CI exercising it against new Laravel releases.

Key questions for engineering

1. What are the exact composer.json constraints, and does it install clean on our current Laravel/PHP?
2. Is the filterable-column allowlist mandatory, or can arbitrary request keys reach the query builder? Show me the dispatch method.
3. Does it handle relationship filters, and if so does it introduce N+1 or unindexed joins?
4. How many lines is the actual implementation? (If <250, the fork-vs-reimplement calculus is decided.)
5. Is there a maintained alternative already in our dependency set (Spatie laravel-query-builder, tucker-eric/eloquentfilter) that covers 90% of the need?
6. Who owns the fork if we take one, and what is the trigger to retire it?

Recommendation: treat this as a reference implementation, not a dependency. Budget 1–2 engineer-days to reimplement the pattern in-house behind an explicit allowlist; that is cheaper than the indefinite carrying cost of a fork.

Integration Approach

Stack fit Directly viable only on a legacy Laravel 5.5–5.8 / PHP 7.x service. On Laravel 8+ the package is not a stack fit — the integration becomes "adopt the pattern." If we are on 5.x and the service is slated for upgrade within two quarters, installing now creates a migration liability we will pay for twice.

Compatibility matrix (to be verified, not assumed)

Migration path

1. Characterize — read the filter dispatch method; document the exact supported operators and edge cases (null, empty string, comma-lists, ? placeholders).
2. Vendor — copy the trait/abstract filter into app/Support/Filtering under our namespace, with a header comment attributing origin and license.
3. Harden — make the allowlist a required, typed property; map public filter names to columns explicitly (['status' => 'order_status']) so request keys never touch the query builder directly; add a hard cap on filter count and reject unknown keys.
4. Test — characterization tests against the vendored behavior, plus negative tests for unknown keys, operator injection, and attempts to filter non-allowlisted columns.
5. Retire the fork — if the surface grows beyond simple equality/like/in, replace wholesale with Spatie laravel-query-builder, which is actively maintained and gives the same ergonomics with a documented security model.

Sequencing Do the audit (half day) before committing to either path — the answer to "how big is the dispatch method" determines fork vs. reimplement. Harden and test in the same PR as the vendor-in; never ship the trait and the allowlist as separate changes. Schedule the replacement evaluation only if filtering requirements expand past scalar equality.

Operational Impact

Maintenance Bus factor of one, and that one has not shipped since 2018. Owning this means owning a fork: tracking upstream Laravel breaking changes (query builder signatures, whereLike semantics, strict-mode default flips) with no upstream to lean on. Estimate ~2–4 hours per major Laravel upgrade to re-validate a vendored copy — acceptable, but it must be an explicit line item somewhere, not ambient hope.

Support No SLA, no security disclosure channel, no maintainer responsiveness. With 11 stars and 0 dependents there is effectively no community to search for answers — every question is answered by reading the source. Onboarding cost is genuinely low (an afternoon), which is also the trap: the low ramp-up disguises the absence of a safety net.

Scaling The filter layer itself is negligible — trait resolution and a handful of where calls per request. The scaling risk is behavioral, not computational: unconstrained filtering invites consumers to build arbitrary queries, which produces unindexed LIKE '%term%' scans, deep offset pagination, and filters on high-cardinality columns. Pair any adoption with per-endpoint query budgets, required pagination limits, and index review for every newly allowlisted column.

Failure modes

• Silent no-op — a misspelled filter key is ignored rather than rejected, so consumers believe a filter applied when it did not. This is the most dangerous one: it produces wrong answers, not errors.
• Allowlist bypass — unlisted key reaches the query builder, causing errors that leak column names.
• Upgrade cliff — a Laravel bump breaks the trait at a moment we do not control, mid-upgrade.
• Scope creep — filtering expands by accretion into a de facto public query API with no versioning or contract tests.
• Combinatorial blowup — consumer-supplied multi-filter requests without caps.

Ramp-up and cost Engineer ramp-up: half a day. Reimplementation: 1–2 days including tests. Ongoing fork carrying cost: low but perpetual. Against that, the package saves perhaps a day of initial development — which is why the honest TPM conclusion is that the economics favor reimplementing the 150-line pattern and spending the saved risk budget on the allowlist hardening and test suite that this package does not ship.