Laravel Simple Query Filter Laravel Package

Technical Evaluation

Architecture fit

• The package is a single trait intended for inclusion in Eloquent models. That is the lightest possible integration surface in Laravel: no service provider, no config publish step, no facade, no middleware. It sits at the "local scope" layer of the framework's query-building conventions, which is architecturally idiomatic.
• Because it lives on the model rather than in a request layer, it implies the model reads request input directly (typical for this class of trait). That is a deliberate architectural trade-off: fast to adopt, but it couples the persistence layer to HTTP and makes the filtering behaviour hard to reuse from jobs, console commands, or internal services.
• Fit is therefore good for a small CRUD/admin surface and poor for domain-driven or API-first codebases where filtering is considered an application-layer concern.

Integration feasibility

• Installation is a one-line Composer require plus a use statement. There is no infrastructure to provision and no runtime service to operate. The realistic engineering effort is a half-day spike, not a project.
• The material constraint is age: last release 2020-09-24, zero stars, zero dependents. That combination almost certainly means the composer.json version constraints target Laravel 6/7 and PHP 7.x. Modern Laravel (10/11/12) and PHP 8.2+ compatibility is unverified and must be proven, not assumed.
• Zero dependents also means no field evidence. There is no public corpus of teams who have run this in production, so every failure mode we care about is undiscovered rather than absent.

Technical risk

• Abandonment risk (high): a 2020 snapshot with no maintainer activity. If the repository is deleted or made private, the dependency disappears from your build. That is a real availability risk for a build pipeline, disproportionate to the value delivered.
• Correctness/security risk (high, unquantified): filter traits typically map request keys to column names. Without an explicit allowlist, that is a mass-assignment-adjacent and SQL-injection-adjacent surface (raw column interpolation, orderBy on arbitrary columns). We cannot assess this without reading the source.
• Maintenance transfer risk (medium): the code is small enough that forking it is cheap, which lowers the risk but also lowers the value of taking the dependency at all.
• Compatibility risk (medium): Eloquent's builder API has shifted (e.g. whereHas/whereRelation, stricter typing in newer versions); an unmaintained trait may emit deprecations or break silently.

Key questions

1. What is the actual filter DSL — query-string keys, a structured filter[...] array, operator prefixes (gte:, like:)? Is it documented?
2. Is there an allowlist of filterable columns, or does it accept arbitrary keys? Any raw SQL string interpolation?
3. Does it read request() inside the model, or accept an array of filters as an argument? The latter is a materially better design.
4. Declared composer.json constraints for laravel/framework and php, and does it have illuminate/* split-package constraints?
5. Is there a test suite and CI at all? Is there a license file?
6. What does it do that a handful of native Eloquent local scopes does not?

Integration Approach

Stack fit

• Appropriate only if the target is a Laravel monolith with existing Eloquent models and a conventional controller → model query flow. It is not appropriate for a codebase standardising on API Resources + query-builder libraries, nor for multi-tenant systems where filter keys must be tenant-scoped.
• The realistic benchmark is not "build vs. buy" but "this trait vs. ~50–150 lines of first-party local scopes" or "vs. a maintained library" (spatie/laravel-query-builder is the de facto standard and has active maintenance, tests, and an allowlist-first design).

Migration path

• Recommended path: vendor the trait into application code (copy into app/Models/Concerns/ under your own namespace, with attribution and license check) rather than adding a Composer dependency. This preserves the ergonomics while eliminating the abandonment and supply-chain risk, and lets us add the allowlist and the array $filters signature that the original may lack.
• If a dependency is preferred for provenance reasons, pin to an exact version and mirror the repository internally; do not rely on Packagist availability alone.

Compatibility

• Gate on a written compatibility check before any commitment: declared PHP/Laravel constraints, a smoke test running the trait against our actual framework version, and static analysis (PHPStan/Larastan) over the vendored file. If it uses request() in the model, treat that as a defect to be patched, not a feature.
• Confirm behaviour under our DB driver; column-name handling that works on MySQL may not on PostgreSQL.

Sequencing

1. Week 1 — Spike (1–2 days): read the source, catalogue the DSL, run it against our Laravel/PHP versions on a throwaway branch, write 5–10 tests covering allowlisting, unknown keys, and operator handling.
2. Week 1 — Decision gate: if the source is allowlist-safe and the DSL covers our needs, proceed to vendoring. If it accepts arbitrary columns or interpolates raw SQL, stop — the package is a template, not a dependency.
3. Week 2 — Adopt: vendor the trait into App\Models\Concerns, add the allowlist, harden the signature to accept an explicit filter array, add tests, document the convention in the team's Laravel style guide.
4. Later — Standardise: if filtering needs grow (sorting, includes, sparse fieldsets), graduate to a maintained library and retire the trait behind the same call site.

Operational Impact

Maintenance

• Ownership transfers to us on day one. That is acceptable here precisely because the artefact is tiny — a file we can read end-to-end in ten minutes — but it must be recorded in the service catalogue as first-party code, not as a third-party dependency we are "waiting on upstream for."
• No upgrade treadmill from the package itself; the treadmill is our framework upgrades, and the vendored file must be covered by the same test suite as the rest of the models.

Support

• Effectively zero: no maintainer, no issue history of consequence, no community to escalate to, no security advisory channel. Any defect is ours to diagnose, and there is no upstream to notify if we find a vulnerability.
• Escalation route must be internal: the platform team owns the vendored concern.

Scaling

• Negligible CPU/memory footprint; filtering is query construction, not application-level processing. The package itself will not be a bottleneck.
• The real scaling exposure is query shape: arbitrary filter keys invite unindexed predicates, LIKE '%…%' scans, and sort-by-unindexed-column. At low data volume this is invisible; at a few million rows per table it becomes p95 latency. Any adoption should come with a rule that filterable columns must be indexed and that free-text search is out of scope.

Failure modes

• Silent no-op: unrecognised filter keys ignored, caller believes a filter applied, gets unfiltered data. Dangerous in export/reporting endpoints and in any "download all" path.
• Injection / column enumeration: unvalidated column names in where or orderBy; error messages that leak schema.
• Framework-upgrade break: deprecation or signature change in Eloquent, discovered in a routine upgrade PR rather than by a test.
• Dependency disappearance: repo removed or made private, breaking clean CI builds.
• Behaviour drift: if the trait is used across many models, per-model overrides accumulate and filtering semantics diverge between endpoints with no central documentation.

Ramp-up

• Very low. A Laravel-proficient engineer understands the trait in under an hour; the spike plus vendoring plus tests is roughly 2–3 engineer-days including review, documentation, and the allowlist hardening.
• The organisational cost is not learning the package — it is the governance overhead of adding a dependency with no maintainer. That overhead likely exceeds the value of the code.

TPM recommendation: treat this as a pattern reference, not a dependency. The reusable idea — declarative model-level query filters — is worth adopting; the specific artefact carries abandonment, security, and compatibility risk disproportionate to its ~100 lines of value. Vendor and harden it, or adopt a maintained equivalent, and document the filterable-column allowlist as the governing standard.