Detective Laravel Package

Technical Evaluation

Architecture fit

• The package targets the Eloquent query builder as a filtering layer — a natural seam for Laravel applications that need declarative, reusable filter definitions instead of ad-hoc when() chains in controllers.
• Intended shape is likely a service provider + trait/filter-object convention, which fits Laravel's package conventions and composes with existing scopes and query builder macros.
• Fit is strongest for read-heavy, list/search endpoints where filter criteria are dynamic and repeated across resources. It is a poor fit for write paths, domain logic, or anything requiring strict type safety at the boundary.
• The critical architectural mismatch is era: a 2016 package targets Laravel 5.x and PHP 5.6/7.0 idioms. Modern applications (Laravel 9–11, PHP 8.1+) will hit Composer constraint conflicts before any code-level incompatibility is even reached.

Integration feasibility

• Low integration effort in principle: small surface area, MIT license, no external services or infrastructure. Adoption is a composer require plus provider registration and trait inclusion.
• Practical feasibility is gated by dependency constraints rather than design. Expect to either pin an old framework branch or vendor/fork the source into app/ or a private package.
• Because the value is concentrated in the filter-resolution logic (a few hundred lines at most), forking is likely cheaper than fighting Composer for a supported install path.

Technical risk

• Abandonment risk (high): last release 2016-10-26, 13 stars, no evidence of maintained CI, security policy, or issue triage. No patch path exists for framework or PHP upgrades.
• Compatibility risk (high): PHP 8 fatal errors from removed/renamed helpers and stricter signatures are plausible; Laravel's service provider and Eloquent builder internals have changed materially since 5.x.
• Security risk (medium): filtering packages frequently map request parameters directly to query columns. Without a verified allowlist, filter keys become an injection and information-disclosure surface. This must be validated before any exposure to untrusted input.
• Supply chain risk (low): no transitive dependency tree to speak of, so the blast radius is confined to the package itself.
• Overall: this is a reference implementation, not a dependency. Score 0.125 is consistent with "read it, don't ship it."

Key questions

• Which Laravel and PHP versions are declared in composer.json, and is illuminate/support bounded or open-ended?
• Does the package validate/allowlist filter keys and columns, or does it trust request input?
• Is filtering applied through Eloquent only, or does it reach into raw query builder clauses and whereRaw?
• Are there tests, and do they run against a matrix of framework versions?
• Does it support relationship filtering, nested params, and pagination composition — or only flat column predicates?
• What is the actual code volume? If it is under ~500 LOC, a fork is trivially defensible; if larger, the calculus changes.

Integration Approach

Stack fit

• Viable only on a legacy Laravel 5.x / PHP 7.0 service that is already pinned and not planning a framework upgrade.
• On a modern stack, do not add it as a dependency. Extract the filter-resolution pattern into first-party code (a Filter base class plus a Filterable trait) and keep the framework at its current version.
• If the team wants a maintained equivalent, evaluate Spatie Query Builder or Eloquent Filter as the replacement rather than porting this package forward.

Migration path

1. Spike (1–2 days): install in an isolated branch against the current framework version. Record exactly where it breaks — Composer resolution, provider boot, builder macro conflicts.
2. Assess (1 day): read the source. Decide fork vs. reimplement vs. replace. Default recommendation: reimplement the ergonomics, not the code.
3. Implement (3–5 days): first-party Filterable trait with explicit per-model $filters allowlist, typed filter methods, and a single applyFilters(Builder, array) entry point. Add contract tests asserting each supported filter maps to expected SQL.
4. Cut over: route filter construction through the new abstraction behind a config flag; keep controller signatures unchanged so the swap is invisible to callers.

Compatibility

• Verify Composer's platform requirements before anything else; a PHP 8 incompatibility is a hard stop, not a workaround.
• Check for reliance on removed helpers (str_*, array_*), Illuminate\Support\Str method changes, and container binding semantics.
• Confirm package auto-discovery (extra.laravel) exists; if not, manual provider registration and facade aliasing are required.
• Eloquent builder changes around whereHas, with, and macro registration should be exercised explicitly, not assumed.

Sequencing

• Blocking dependency: the fork/reimplement decision must land before any feature work builds on filter semantics.
• Filter allowlists are a prerequisite to exposing endpoints publicly — sequence security review before the first external release.
• Defer relationship and nested filtering to phase two; ship flat, allowlisted predicates first and measure query performance before expanding.

Operational Impact

Maintenance

• Ownership transfers entirely to the adopting team. There is no upstream to merge from, so every framework upgrade becomes a local patch exercise.
• Budget a standing, low-but-nonzero maintenance cost: re-validating filter behavior on each Laravel minor, plus periodic review of the forked code for query-shape regressions.
• Record the fork provenance and license text; MIT permits this, but attribution should be preserved.

Support

• No vendor, no SLA, no maintainer responsiveness. Bus factor of one, and that one has been inactive for roughly nine years.
• Internal support burden falls on whoever owns the fork. Institutional knowledge concentrates in one or two engineers — mitigate with documentation and tests.
• 13 stars means effectively no community to consult; Stack Overflow coverage for the specific API will be near zero.

Scaling

• Filtering cost is query-shape cost. Unindexed filter columns will produce full scans as data volume grows, and the package does not help you detect this.
• Watch for N+1 patterns if relationship filtering triggers lazy loads, and for combinatorial whereHas subqueries on large tables.
• No caching, batching, or query-planning features — treat it as query construction only, and place caching at the application layer.
• Complex multi-filter requests can generate unpredictable SQL; instrument query time and log slow filter combinations from day one.

Failure modes

• Hard failure: framework upgrade breaks provider boot or builder macro registration, taking down every endpoint using filters at once.
• Silent failure: filter key no longer matches its column, producing unfiltered results that look correct — the most dangerous class, and the reason contract tests are mandatory.
• Security failure: unvalidated filter keys allow column enumeration or injection against an endpoint exposed to untrusted clients.
• Performance failure: a newly added filter lacks an index; the endpoint degrades gradually and is only noticed under production load.
• Behavioral drift: undocumented filter semantics diverge between the forked code and the original, making external references misleading.

Ramp-up

• Learning curve is genuinely low — likely a trait and a small set of filter conventions. A mid-level Laravel engineer is productive in under a day.
• The real ramp-up cost is documentation debt: the supported filter vocabulary, allowlist rules, and parameter naming must be written down and kept current.
• Onboarding new engineers onto a forked, unmaintained package requires an explicit "this is ours now" briefing; otherwise it is mistaken for a live dependency and treated as a black box.