Form Filter Bundle Laravel Package

Technical Evaluation

What this release actually is. v12.3.0 contains two changes: a docs migration to VitePress (PR #54) and a new profiler capability that traces filter-state persistence (PR #53). There are no breaking changes, no deprecations, and no new public API surface implied by the notes. This is a low-risk, additive minor release.

Architecture fit — the headline finding. Despite being framed as a "Laravel/PHP package" in the review request, SpiriitLabs/form-filter-bundle is a Symfony bundle, not a Laravel package. It integrates via Symfony's bundle registration, service container, form component, and — as of this release — the Symfony WebProfiler. It will not install or function idiomatically in a Laravel application without substantial adaptation (service-provider bridging, form-component divergence, profiler incompatibility). If the target stack is genuinely Laravel, architecture fit is poor and this should be escalated before any integration work begins. If the target stack is Symfony, fit is good — it occupies a well-defined niche (declarative, reusable filter objects bound to Doctrine queries) that otherwise gets hand-rolled inconsistently per project.

Integration feasibility. Low effort on Symfony: composer require, register the bundle, define filter classes, wire into controllers/forms. The new profiler tracing is opt-in tooling that improves debuggability of a genuinely fiddly area (filter state surviving across requests via session/query string) without changing runtime behavior. On Laravel: not feasible without a wrapper layer, and I would not recommend building one for a single package — the effort likely exceeds reimplementing the pattern natively with Eloquent scopes and form requests.

Technical risk. Low on the release itself. The main risks are contextual: (1) framework mismatch as above; (2) v12.x is a mature major line, so we inherit whatever conventions and constraints it locked in — the docs move to VitePress is cosmetic but signals a docs-site dependency; (3) we hold only release notes, not the source, changelog history, test coverage, or maintainer cadence, so this assessment is provisional; (4) a two-PR release from a small maintainer team implies bus-factor exposure worth checking before adopting.

Key questions.

• Is our target stack Laravel or Symfony? This determines whether the assessment continues at all.
• What is the package's install base, release cadence, and open-issue/PR ratio over the last 12 months?
• Does the filter-state persistence feature have known edge cases (nested filters, pagination, multiple filter sets on one page)?
• Who maintains it, and is there a funded commercial backer or is it volunteer-only?
• What is the upgrade policy across majors — does v12 signal stability or churn?
• Do we already have an internal filtering convention that this would duplicate or replace?

Integration Approach

Stack fit. Symfony 6.4/7.x with Doctrine ORM and Twig is the intended home; the bundle leans on the Form component and, now, the Profiler. Laravel is out of scope without a bespoke adapter. Before sequencing anything, confirm the stack — everything below assumes Symfony.

Migration path. If we have ad-hoc filtering (repository methods with conditional query builders, or controller-level request parsing), the path is incremental and low-drama: introduce filter classes per entity, bind them to list/index actions first, leave write paths untouched, and run old and new filtering in parallel behind a feature flag on one or two low-traffic admin screens. Because the release is non-breaking, adopting v12.3.0 directly as the baseline is fine — no need to stage through v12.2.0.

Compatibility. Verify PHP version floor and Symfony minor constraints against our runtime before committing; a v12 major normally targets a modern PHP floor and may drop older Symfony minors. The VitePress docs change is irrelevant at runtime. Confirm the profiler tracing degrades gracefully when web_profiler is absent in production — it should, but that is exactly the class of thing to verify rather than assume.

Sequencing.

1. Stack confirmation and go/no-go (blocking).
2. Dependency and version-floor audit against our runtime and CI matrix.
3. Proof of concept on one non-critical admin listing, including the new profiler tracing in dev to validate the debuggability claim.
4. Define an internal convention for filter-class placement and naming so adoption does not fragment.
5. Roll out to remaining listings; document the pattern; retire the parallel path.
6. Only then consider whether the profiler tracing earns a place in our standard dev workflow.

Operational Impact

Maintenance. Low ongoing cost. One bundle, small surface area, declarative filter classes that are easy to read and review. The real maintenance burden is convention drift — without a documented internal standard, every developer will structure filters slightly differently, and the package will silently become three patterns in a trench coat. Assign an owner and write the convention down early.

Support. The maintainer team appears small (two contributors visible in this release), so upstream support is best treated as "community, best-effort." Budget for the possibility of pinning to v12.3.0 and carrying a small patch ourselves if an upstream fix stalls. The VitePress docs migration slightly increases our dependence on an external docs host; mirror anything critical into our own onboarding notes.

Scaling. Runtime scaling is not a concern — filtering is request-scoped query construction, and the bundle adds no persistent state or background work. Scaling risk is organizational: onboarding cost rises with each undocumented internal variant of the pattern. The new profiler tracing actually helps here, giving new joiners a visible window into how filter state persists across requests, which is the least intuitive part of the abstraction.

Failure modes.

• Framework mismatch surfacing late — someone attempts a Laravel install and burns a sprint. Mitigate by settling the stack question first.
• Silent filter-state leakage — persisted filter state bleeding between users, sessions, or paginated views. The profiler tracing in this release is precisely the tool to catch this; treat it as a mitigation, not a nice-to-have.
• Upstream abandonment — small team, no visible commercial backing. Mitigate with a version pin and a documented fork-and-patch runbook.
• Convention fragmentation — duplicated or conflicting filtering logic. Mitigate with the written standard and code review.
• Profiler coupling — dev-only tooling leaking assumptions into production paths. Verify the dev/prod boundary.

Ramp-up. Modest for a Symfony developer already comfortable with the Form component and Doctrine — call it one to two days to first productive filter class, roughly a week to confident independent use including the persistence and profiler behavior. For a Laravel-only team, ramp-up is effectively undefined because the package does not fit; estimate the cost of building and owning an adapter before treating it as an option.

Verdict on this release. v12.3.0 does not change the adoption calculus — it is a docs refresh plus a developer-experience improvement. If a Symfony integration is already underway, upgrade without ceremony. If the request is still being framed as a Laravel package, that framing is the finding, and it needs resolving before the release notes matter at all.