Filter Bundle Laravel Package

Technical Evaluation

Architecture fit — the deciding finding. pugx/filter-bundle is a Symfony bundle, not a Laravel package. It is constructed around the Symfony bundle/DI-extension model, the Symfony Form component, Doctrine ORM entity metadata, and kernel request handling. None of these have a supported equivalent in Laravel's service-provider, Eloquent, or HTTP-kernel model. There is no service provider, no config/filter.php, and no facade — Composer autodiscovery will not wire it. For a Laravel application the fit is poor to none, and this is a "wrong framework" finding rather than a "needs a thin adapter" finding. The correct comparison class is Spatie Query Builder, Eloquent Filter, or an in-house filter abstraction.

What the package actually does. It turns request parameters into Doctrine QueryBuilder conditions via annotations/attributes declared on entities: you write a FilterType extending the bundle's base form type, bind the request, receive an immutable Filter value object, and apply it to a builder. The value is real but is entirely bound to the Symfony Form + Doctrine combination.

Integration feasibility. Two positions only:

1. Not feasible for Laravel services. The effort to wrap it would exceed the cost of a native equivalent and would leave us maintaining a bespoke bridge over an upstream we do not control.
2. Feasible if we operate Symfony + Doctrine services. In that context it is a small, well-scoped, single-purpose dependency that does one job well.

Technical risk.

• Ecosystem mismatch (high, permanent): it will never be a first-class citizen in a Laravel codebase.
• Adoption and bus factor (high): 7 stars and a very small maintainer footprint. This is not a mainstream dependency; support is effectively "open an issue and wait."
• Statefulness signal (medium — and the real content of v1.7.1): the release fixes filter forms being keyed positionally and retaining values across requests. That prior assumption of a classic PHP-FPM lifecycle is exactly the class of bug long-lived-worker deployments (Octane, Swoole, RoadRunner, FrankenPHP worker mode) surface. Treat per-request state hygiene as something to verify, not something already solved.
• Doctrine metadata coupling (medium): annotation-vs-attribute parsing and Doctrine ORM 2/3 skew is a recurring breakage source.
• Licensing (low): LGPL-3.0 is fine for unmodified dependency use but imposes obligations if we fork or vendor-modify — relevant given the fork mitigation below.

Key questions for the review.

• Do we operate any Symfony/Doctrine services, now or on the roadmap? If no, this evaluation terminates here.
• If yes: which PHP, Symfony, and Doctrine ORM versions are pinned, and is v1.7.1 inside that matrix?
• Are those services deployed on long-lived workers, and have we observed the filter-form bleed this patch addresses?
• Who owns upgrade decisions for a third-party bundle with no vendor SLA and near-zero community mass?
• Is the capability already covered by a Laravel-native filter/query library in our stack, creating needless pattern duplication?
• For Laravel-scoped work: is the desired outcome "declarative filtering" (substitutable) or specifically "Symfony annotation-driven filtering" (not substitutable)?

Integration Approach

Stack fit. Against a Laravel reference architecture: does not fit — do not attempt it. Against a Symfony + Doctrine reference architecture: fits cleanly, as a conventional narrowly scoped bundle that plugs into the Form and Doctrine layers without imposing its own runtime.

Migration path. There is no migration path into Laravel, and none should be attempted.

• Adopt (Symfony only): add the Composer dependency, register the bundle in config/bundles.php, annotate the target entities. v1.7.1 is a drop-in from v1.7.0 — no config or code changes.
• Substitute (Laravel): satisfy the underlying need — declarative, form-driven, whitelisted filtering of queryable resources — with a Laravel-native library or a thin in-house FiltersQuery/scope class that whitelists keys and applies when()/filled() clauses. Record this bundle as explicitly out of scope so it is not re-proposed.

Compatibility. Patch-level and backward compatible. The behavioural change is that filter forms are now identified by name rather than ordinal position, and no longer persist values between requests. Code that indexed into the filter form collection numerically, or that relied on stale values surviving a request, can observe different behaviour. Audit custom form themes, Twig templates, and tests that index into the collection before upgrading.

Sequencing.

1. Confirm Symfony presence and version matrix — this is a blocking gate; stop here if negative.
2. Grep the adopting service for numeric indexing into filter forms and for custom form themes — the only realistic regression surface.
3. Upgrade v1.7.0 → v1.7.1 in a non-production environment; run the filter/form test suite.
4. Where long-lived workers are in play, add an explicit regression test: two sequential requests with different filter values, asserting no bleed.
5. Promote; no config or infrastructure change required.
6. In parallel, publish an internal decision record for the Laravel estate naming the framework mismatch as the deciding factor.

Operational Impact

Maintenance. Low ongoing effort for an adopting Symfony team — small surface, stable behaviour. The risk is not churn but the absence of it: low release cadence means upstream fixes arrive slowly and any workaround we write we carry indefinitely. Budget for the possibility of vendoring or forking if the project stalls, and note the LGPL-3.0 obligations that come with a modified fork.

Support. Community-only. No vendor SLA, no commercial backing, no escalation path beyond an upstream issue. Acceptable for a presentation-layer concern; it must not become load-bearing for anything with an availability commitment.

Scaling. Stateless by design after this patch and therefore not a horizontal-scaling constraint. Cost scales with query complexity rather than request volume. Note the familiar trap: Contains produces LIKE '%term%', which cannot use a B-tree index — on large tables prefer prefix search or a full-text index, and ensure every filterable column is actually indexed. Loose application of entity attributes also invites N+1 queries; that is code-review discipline, not a package defect.

Failure modes.

• Form-state bleed across requests — the defect this release fixes; previously manifested as a search box "remembering" a query nobody typed, most visibly under Octane/Swoole or repeatedly booting kernels in functional tests.
• Numeric-index assumptions — custom templates or tests keyed to filter collection positions break silently after the name-keying change.
• Doctrine metadata/attribute drift — Doctrine ORM major upgrades can break attribute discovery.
• Abandonment — no maintainer response to a blocking bug; mitigation is vendoring, with license review.
• Mis-scoping — the most likely operational failure is a Laravel engineer attempting to reuse this pattern and hand-rolling an incompatible equivalent mid-sprint.

Ramp-up. For a Symfony-fluent engineer: under a day — it follows framework conventions and the three classes that matter (FilterType, FilterBuilder/Filter, the annotation classes) are quick to learn. For a Laravel-only team: effectively not ramp-up-able. The prerequisite knowledge is bundles, DI extensions, Doctrine metadata, and Symfony Forms — a multi-week learning curve for a capability with cheaper native alternatives. Treat onboarding cost as prohibitive and route the team elsewhere.

Recommendation. Approve v1.7.1 as a routine patch for any Symfony service already consuming this bundle, contingent on the numeric-index audit and, where long-lived workers are used, a two-request state-bleed regression test. Do not introduce it into the Laravel estate; record the framework mismatch and the 7-star bus factor as the deciding factors and close the evaluation for Laravel-scoped work.