Filtan Laravel Package

Technical Evaluation

Architecture fit

• Filtan occupies the HTTP-to-Eloquent boundary: translate request parameters into constrained WHERE/relation clauses on an Eloquent\Builder. That is the right seam for a filter abstraction — it keeps controllers thin and keeps query composition out of models — and it composes cleanly with Laravel's existing idioms (form requests, middleware, scopes, resource classes).
• It is additive and shallow: no schema changes, no new infrastructure, no service provider-level coupling beyond the package's own registration. That makes it architecturally cheap to evaluate and architecturally cheap to remove.
• The design tension to validate is resolution strategy. Filter packages generally fall into two camps: convention-driven (parameter name maps to column) and allowlist-driven (explicit filter classes/maps). Convention-driven is faster to adopt and materially riskier — it turns arbitrary query-string keys into query predicates unless column allowlisting is enforced. Filtan's camp is the single most important thing to confirm before adoption.
• It overlaps with the incumbent in this niche (Spatie's laravel-query-builder, Eloquentify, hand-rolled base filters). The build-vs-adopt question is really adopt-A-vs-adopt-B, and the differentiator should be the allowlist/operator model, not feature count.

Integration feasibility

• High, and low effort. Composer install, apply the trait/base filter, opt in per endpoint. Realistic estimate: half-day spike on a branch against three representative endpoints, then 2–5 engineer-days to wrap it behind an internal contract plus tests before any production exposure.
• No migration or backfill work. Existing hand-rolled filters can be left in place while Filtan covers new endpoints, so the change is reversible at endpoint granularity.
• The main integration cost is not the package — it is writing the allowlist/contract tests and the internal wrapper that prevents the package's API from leaking into every controller.

Technical risk

• Adoption signal is the dominant risk, not code quality (which we have not seen). 2 stars, 0 dependents, a single maintainer, and a last release in November 2024 mean essentially zero downstream validation. There is no population of users who have already found the edge cases for you.
• Bus factor is 1. No deprecation policy has been demonstrated, so a patch release is not a safe assumption of backward compatibility.
• Framework drift: a late-2024 release may or may not declare support for the newest Laravel major and current PHP versions. Verify composer.json constraints against your actual upgrade horizon, not just today's runtime.
• Security posture is unverified. Anything that maps request input to query structure needs allowlisted columns, allowlisted operators, and fail-closed behavior on unknown parameters. If Filtan does not enforce this, you must, in the wrapper.
• Silent-failure risk is the sharpest technical concern: a filter that is silently dropped returns more data than intended, with a 200 response and no error. That class of bug is found by users, not by monitoring.

Key questions

• Does it require an explicit allowlist of filterable columns and operators, or does it infer them from parameter names?
• What happens on an unrecognized parameter — 400, ignore, or attempt to apply?
• Which operators are supported (=, >, in, like with wildcards, null, date ranges), and are they validated server-side?
• Does it support relation/nested filters, and does it prevent N+1 when filtering on related models?
• How does it compose with sorting and pagination, and does it mutate the builder in place or return a new one?
• Does it interact correctly with global scopes, soft deletes, and policy-driven query constraints (multi-tenancy being the critical case)?
• What Laravel and PHP version ranges are declared, and is there a CI matrix and test suite we can read?
• What is the license, and is there any indication of intended long-term maintenance?
• Are there any performance characteristics documented for many-filter or high-cardinality cases?

Integration Approach

Stack fit

• Assumes a conventional Laravel + Eloquent stack. It is a poor fit where filtering already runs through a repository layer or raw query builder, since it would introduce a second, competing composition path.
• If the codebase is on Spatie's query builder, adopting Filtan is a lateral move with migration cost and no clear payoff. If filtering is currently copy-pasted across controllers, Filtan is a genuine consolidation win.

Migration path

• Greenfield endpoints first; no migration required for new work.
• For existing endpoints, introduce an internal QueryFilter contract that Filtan implements. Controllers depend on the contract, not the package. This converts a potential future fork or replacement into a one-file change.
• Leave existing hand-rolled filters untouched until their endpoint has contract-test coverage. Never migrate a filter and add its tests in the same change.

Compatibility

• Pin an exact version (composer require with a tight constraint), commit the lockfile, and run the app's full test suite — not just filter tests — after install.
• Validate against the actual Laravel major you will be on at the next upgrade, not only the current one. If the package does not declare support for your upgrade target, assume you will maintain a fork and price that in.
• If anything in the resolution path is unacceptable, vendor the package into the repo rather than forking on GitHub — it makes the maintenance obligation visible in code review.

Sequencing

1. Spike branch: three endpoints covering equality, a multi-operator filter, and one relation filter.
2. Security review of the resolution path — allowlisting, operator validation, unknown-parameter behavior, multi-tenancy interaction.
3. Write the internal contract and wrapper; make Filtan an implementation detail behind it.
4. Contract tests that assert both the positive case and the fail-closed case (unknown param must not widen the result set).
5. Roll out to low-blast-radius read endpoints only.
6. Re-evaluate after 30 days against real usage; expand, hold, or replace.

Operational Impact

Maintenance

• Treat this as an internally-owned dependency from day one. The realistic steady-state cost is nonzero: version bumps, Laravel major upgrades, and the strong likelihood that you fork when the next framework major lands.
• Set a review trigger: if the package has no release for two framework majors, or if the maintainer becomes unresponsive for a quarter, execute the fork plan. Do not let this be discovered during an upgrade crunch.

Support

• Community-only, single maintainer, no SLA. With 2 stars and 0 dependents, issues may go unanswered and there is no crowd to consult.
• Budget for self-support: the team that adopts it owns debugging it. That should be an explicit acceptance, not an implicit one.

Scaling

• Query filtering is in-process and computationally trivial; this is not a horizontal-scaling concern.
• The scaling risk is query complexity. Filters that hit unindexed columns, leading-wildcard LIKE, or deep relation joins turn a cheap endpoint into a table scan under load. Enforce a filterable-column allowlist aligned with the index set, cap the number of applied filters, and instrument slow-query logging per endpoint.
• Watch for relation filters that bypass eager loading and produce N+1 behavior that only appears at production cardinality.

Failure modes

• Silent under-filtering (highest severity): an unrecognized or malformed parameter is ignored, the endpoint returns a broader result set than intended, and nothing alerts. Mitigate with fail-closed contract tests and explicit rejection of unknown filter keys.
• Silent over-filtering: a renamed column or changed operator silently returns empty sets. Cheap to detect with assertion tests on known fixtures.
• Injection-class defects: if column or direction names reach the query builder without allowlisting, this is an injection surface. Verify, do not assume.
• Abandonment: framework upgrades blocked by a stale constraint, discovered late. Mitigate with the wrapper plus a scheduled dependency review.
• Breaking patch release: bus-factor-1 projects have no demonstrated compatibility discipline. Pinning and lockfile discipline is required, not optional.

Ramp-up

• Low for any Laravel-fluent engineer — hours, not days. The API surface of a filter package is small.
• The real onboarding cost is the convention: which columns are filterable, which operators are legal, how unknown input is handled, and where filtering sits relative to authorization. Document that once, in the wrapper, and the package itself becomes almost invisible to the team.

Verdict

• Viable for internal, low-blast-radius read endpoints, adopted behind an internal contract and a strict allowlist, with a fork plan on the shelf.
• Not appropriate for authorization-sensitive or multi-tenant query paths until the allowlisting behavior has been verified by test, and not appropriate anywhere the team is unwilling to own the dependency outright.