Eloquent Api Filter Laravel Package

Technical Evaluation

Summary position: Low-maturity, single-maintainer package in a functionally commoditized space, carrying a copyleft license that is incompatible with most commercial Laravel product baselines. The technical capability is real but thin; the strategic risk is disproportionate to the value delivered. Recommendation: do not adopt into product code without a legal gate; treat as a reference implementation or replace with a permissively licensed equivalent.

Architecture fit. The package decorates the Eloquent query builder from the HTTP request, which is a natural fit for a Laravel MVC / API-resource architecture and requires no deviation from framework conventions. The architectural concern is where it sits: it couples the public API contract directly to database column names and operators. That means column renames become breaking API changes, sensitive columns become externally addressable unless explicitly allowlisted, and the filter grammar becomes a de facto versioned interface with no versioning mechanism. For an internal or short-lived service this is acceptable; for a public or partner-facing API it is a liability that will be paid for at the first schema migration.

Integration feasibility. Expected to be a standard Composer install with package auto-discovery and a model-side trait or scope. The practical friction is dependency resolution: the last release predates Laravel 11, so illuminate/* constraints may block or require --ignore-platform-reqs-style workarounds on current Laravel. Verify against your actual pinned versions before assuming it installs cleanly.

Technical risk.

1. License (blocking). GPL-3.0 is strong copyleft. Many legal teams treat a GPL PHP library linked into a proprietary application as contaminating the combined work; the FSF position leans that way and the counter-argument is contested. Even where internal-only use is defensible, the obligation attaches on distribution. This alone typically fails enterprise OSS review.
2. Bus factor of one. No foundation, no corporate sponsor, no evidence of funded maintenance. Abandonment is the base case, not the tail risk.
3. Unvetted security surface. Parsing user-supplied keys and operators into SQL is exactly the code path where injection and information-disclosure bugs live. With 10 stars there is no crowd-sourced scrutiny.
4. Information disclosure via filter oracle. Without a strict allowlist, clients can probe hidden or sensitive columns (e.g. is_admin, email, internal flags) by observing result sets — a disclosure channel that does not require the column to be serialized in the response.
5. Silent-failure ergonomics. Unknown or malformed filters are commonly ignored rather than rejected, producing quietly wrong responses that are expensive to debug in production.

Key questions for the maintainer / spike.

• Is there an explicit, developer-declared allowlist of filterable columns and relations, and is it deny-by-default?
• How are operators parsed, and is the grammar strictly validated (closed set) or string-interpolated?
• What is the behavior on an unknown filter or invalid operator — 400, ignore, or 500?
• Supported Laravel/PHP version matrix, and is there CI across those versions?
• Is there a test suite with meaningful coverage of adversarial inputs, and a security disclosure policy?
• Does relation filtering generate joins or N+1 lazy loads?
• Is there any commitment to semver, deprecation notice, or a support window?
• Has the maintainer responded to issues/PRs in the last 12 months?

Integration Approach

Stack fit. Assumes a conventional Laravel + Eloquent stack on PHP 8.x. No framework exotica, no queue or cache dependency, no service infrastructure — it is a query-builder concern only. It will not fit non-Eloquent data access (raw query builders, repository abstractions over multiple sources, or read models backed by something else), and retrofitting it into those is not worthwhile.

Build-vs-buy. This is the central decision, and it should be framed honestly as buy vs. borrow vs. build:

The capability here is ~150 lines of well-understood code. The package's entire value proposition is avoiding that writing. Against a blocking license and a single-maintainer dependency, the arithmetic does not favor adoption.

Migration path. If already present somewhere in the codebase, do not rip-and-replace blindly. Wrap it: define an internal FilterableQuery interface or a base query-object that owns allowlist declaration and operator parsing, and make the package one implementation behind it. That converts a future swap into a one-file change and gives you a place to enforce deny-by-default regardless of what the package does natively. If it is not yet present, the migration path is simply don't — adopt the MIT alternative and port the endpoint contract.

Compatibility. Two concrete checks before any code is written: (1) composer why-not against your pinned Laravel and PHP versions, since a January 2024 release likely predates Laravel 11/12 and may not have been re-tagged for PHP 8.3/8.4 deprecations; (2) whether the package's filter grammar can express the queries your existing API consumers already send — a divergent grammar is a breaking change for clients and the hidden cost of any swap.

Sequencing.

1. Legal gate (do this first, not last). OSS review against GPL-3.0 policy. If it fails, the evaluation ends here and the technical work is redirected.
2. Contract definition. Write down the filter grammar and column allowlist as a spec independent of any library, so the implementation is swappable.
3. Spike. One non-production branch, one real list endpoint, adversarial inputs included.
4. Security review. Focused code read of param parsing; confirm allowlist enforcement and failure behavior.
5. Pilot. 1–2 read-only, low-traffic list endpoints with instrumentation on query time and error rate.
6. Reassess. Compare against the spike of the MIT alternative using the same contract spec; decide on evidence.

Do not parallelize steps 1 and 2 — sequencing the legal gate first avoids spending engineering days on a package you cannot ship.

Operational Impact

Maintenance. Effectively unmaintained in any commercial sense. Plan to vendor, fork, or replace within a 12–24 month horizon. A fork is legally straightforward under GPL but converts an external dependency into an internal one you now own, staff, and patch — which is strictly worse than writing the equivalent in-house under your own license. There is no deprecation policy to plan upgrades against, so Laravel major upgrades become a bespoke compatibility exercise each cycle.

Support. Community-only via GitHub issues, with no SLA, no security contact policy, and a tiny user base that will not surface bugs before you do. Escalation path is "read the source yourself." For a production dependency with revenue attached, that is not a supportable posture.

Scaling. Filtering is delegated to the database, so scaling is a function of indexing discipline rather than the package. Two structural costs to budget for: unbounded filtering and sorting on unindexed columns produce full table scans that will not appear in application metrics until the table is large; and relation filtering, if implemented via lazy loading rather than joins, reintroduces N+1 under exactly the query shapes most likely to be hit by API clients. Mitigations are conventional — cap the number of active filters, restrict sortable columns to indexed ones, require pagination, and add per-route rate limits — but they must be built by you, since the package does not supply them.

Failure modes.

The two most dangerous rows are the ones that fail quietly — disclosure and silent filtering — because neither generates an alert and both surface as a client complaint months later.

Ramp-up. The library surface is small; a mid-level Laravel engineer is productive in under a day and fully fluent in a week. The learning cost is not the API — it is the conventions you must invent around it: the allowlist declaration pattern, the operator grammar you expose, error semantics for invalid filters, and the API documentation that describes all of it. Budget roughly a day of integration effort and 3–5 days of engineering plus review for the security posture and governance layer the package does not provide. The dominant cost is the legal gate and the ongoing ownership of a fork you did not want.

Bottom line for planning. Do not put this on a delivery critical path. Open the legal review, spike the MIT alternative against the same contract, and reserve adoption for the narrow case where an internal-only, non-distributed service needs filtering in a single sprint and the license has been explicitly cleared in writing.