Form Filter Bundle Laravel Package

Product Decisions This Supports

• Buy vs. build for filtered listings. This bundle supplies the plumbing behind form-driven filtering of Doctrine collections: filter definitions, form types, query building, and persistence of the selected filter state across requests. That is a recurring, low-differentiation build for any product with back-office tables, catalogs, or search-result pages — a candidate for adoption rather than in-house maintenance.
• Admin/back-office UX roadmap. Persisted filter state (filters surviving navigation, pagination, and page reloads) is a tangible UX item that users ask for by name. This package makes it a configuration exercise rather than a feature project.
• Debuggability as a roadmap investment. v12.3.0 adds profiler tracing of filter-state persistence. This moves "why did my filters reset / why is this query slow" from guesswork into the Symfony profiler, which supports decisions about how much internal tooling we fund versus buy.
• Scope and platform fit. Note the caveat plainly: this is a Symfony bundle (spiriitlabs/form-filter-bundle), not a Laravel package. Decisions here apply to Symfony services only. If the relevant surface is Laravel, this is out of scope regardless of release quality.
• Version pinning / upgrade planning. v12.3.0 is additive: documentation move to VitePress and a profiler feature. No breaking changes and no deprecations, so it does not force a decision — it removes friction from one we may already want to make.

When to Consider This Package

Consider it when:

• The application is Symfony and the filtered data lives in Doctrine ORM/ODM entities or repositories.
• Filtering is expressed as forms (the familiar FormType model) and the team wants validation, CSRF, and field types for free rather than hand-rolling query-string parsing.
• Users expect filter state to persist — across pagination, sorting, and re-entry — and we do not want to own that state machine.
• We are standardization-minded: one filtering approach across many admin screens is cheaper to document, test, and hand over than N bespoke implementations.
• We want the maintenance risk externalized to a maintained upstream with an active release cadence and a working profiler integration for support.

Look elsewhere when:

• The stack is Laravel or plain PHP without Symfony's Form/HttpKernel components — the bundle's value proposition does not transfer.
• Search requirements are relevance-ranked, faceted at scale, or full-text: Elasticsearch/OpenSearch, Meilisearch, or API Platform's filter layer are the right tools; this bundle is not a search engine.
• The data source is not Doctrine, or filtering is trivial (a handful of fixed WHERE clauses) — a small custom query object is less to learn and less to upgrade.
• The team cannot absorb an upstream major-version cadence, or the project is pinned to a Symfony version outside the bundle's supported matrix.
• Filtering is a genuinely differentiating product surface — in that case bespoke control may be worth the cost.

How to Pitch It (Stakeholders)

To executives: We have a recurring, undifferentiated need — filterable lists that remember what the user selected. This is a maintained open-source Symfony component that already solves it. Adopting it converts a repeated build cost into a dependency, and the newest release (v12.3.0) adds profiler visibility so support can diagnose filter behavior without engineering time. Risk is low: no breaking changes, no deprecations, additive only.

To engineering: v12.3.0 is a safe, non-forcing upgrade. Two changes: docs migrated to a VitePress site (better onboarding surface, no runtime impact), and a profiler data collector that traces filter-state persistence — useful for verifying that filters are being written to and restored from the session/query string as expected. Pin to v12.3.0 if you want the profiler tooling; otherwise v12.2.0 remains functionally equivalent. Confirm the bundle's supported Symfony matrix matches our pinned version before adopting, and confirm the stack is Symfony/Doctrine — this does not apply to Laravel services.