Filter Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for search/filter UX. This package answers a recurring backlog ticket — "add filtering and sorting to the admin list screen." As a PM, the useful framing is that the capability (declarative, form-driven filtering over a queryable resource) is commodity, not differentiating. The decision to make is not "which package" but "do we spend engineering weeks hand-rolling filter forms, or adopt a small library and spend that time on the roadmap item the filter screen exists to serve?"
• Roadmap scoping for admin/internal tooling. Annotation-driven filters plus automatic QueryBuilder application means a list screen with a search form becomes a form class plus entity attributes rather than a bespoke query layer. That is a real velocity argument for internal tools, back-office CRUD, and reporting screens — exactly the surfaces where users judge us on "can I find the record" and where we get no credit for elegant code.
• Platform standardization. This is the load-bearing decision. The package is a Symfony bundle built on Doctrine, not a Laravel package. If our estate is Laravel-centric, the honest PM output is a no, recorded explicitly so it stops being re-proposed — and the pattern (request → validated form → immutable filter → query → paginate) gets reimplemented natively. If we operate any Symfony/Doctrine services, this becomes a cheap, well-scoped yes for those services only.
• Consistency over cleverness. Where multiple list screens exist, "one filter type per screen, whitelisted fields, blank form equals unfiltered set" is a product-quality standard, not just a code convention. It protects against the classic failure where an empty search returns zero rows and the user concludes the data is missing.
• Risk surfacing into planning. The v1.7.1 release is a patch, but its content matters to planning: filter forms were previously not reset between requests, producing "the search box remembers a query nobody typed." Any roadmap item that moves us onto long-lived workers (Octane, RoadRunner, Swoole, FrankenPHP worker mode) turns this from a historical bug into an active verification task.
• Sorting as a separate decision. Keep a maintained whitelist of sortable columns. Users ask for "sort by anything"; supporting it blindly is how a list screen becomes a database incident.

When to Consider This Package

Consider it when:

• The service is Symfony with Doctrine ORM. This is the near-hard gate. Under Laravel, there is no service provider, no auto-discovery, no config bridge — treat it as a reference implementation, not a dependency.
• The need is list-screen filtering and sorting, repeated across several resources, and the team is already fluent in Symfony Forms and Doctrine metadata.
• You are on a classic request lifecycle or are prepared to verify per-request state hygiene under long-lived workers.
• You value a small, single-purpose, stable dependency over a framework with its own runtime and opinions.
• You are already on v1.7.0 — v1.7.1 is a drop-in patch with no API breaks, and it is the minimum to adopt if a page renders more than one filter or you deploy under workers.

Look elsewhere when:

• The estate is Laravel/Eloquent. Use a native query-filter library or a thin in-house FiltersQuery scope, and record this bundle as out of scope.
• You need vendor support, an SLA, or a predictable release cadence. This is community-maintained with a small footprint; a blocking bug may sit. Anything with an availability commitment should not depend on it.
• The filtering requirement is genuinely complex — full-text relevance, faceted search at scale, permissions-aware result sets. Contains compiles to LIKE '%term%', which cannot use a B-tree index; on large tables you want prefix search or a real search index, and that is a different product decision.
• The team has no Symfony background. Ramp-up is measured in weeks for a capability with cheaper native alternatives — prohibitive.
• You are on a Doctrine version outside the supported matrix or rely on annotations where attributes are expected. Metadata drift across ORM majors is a recurring breakage source.

How to Pitch It (Stakeholders)

To executives — one paragraph. This is a small, free, open-source utility that removes hand-written work from a repetitive class of screen: the searchable, sortable admin list. It does not differentiate the product and it does not touch the customer-facing experience; it is a cost-avoidance lever on internal tooling. The recommendation is narrow and deliberate: adopt it only where we already run Symfony, where it is a low-risk drop-in patch with no migration cost, and do not introduce it into our Laravel services — the framework mismatch is permanent and wrapping it would cost more than the native alternative. Exposure is limited to a community-maintained dependency with no vendor SLA, so it must stay a presentation-layer convenience and never become load-bearing for anything with an availability commitment.

To engineering — the ask.

• If Symfony/Doctrine: take v1.7.1. It is a patch — no deprecations, no public API changes. Before promoting, grep for numeric indexing into filter form collections and for custom form themes, since forms are now keyed by name rather than position. If you run long-lived workers, add a regression test that issues two sequential requests with different filter values and asserts no bleed. Then write one filter type per list screen, name every filter explicitly, whitelist the filterable and sortable fields, and assert that an empty form returns the full set.
• If Laravel: do not attempt an adapter. Copy the shape — request in, whitelisted keys, immutable filter value object, applied through when()/filled() in a repository method — and keep controllers away from the query builder entirely. Treat the upstream package as a design reference and close the evaluation.
• Either way: index every filterable column, prefer prefix search over %term% on large tables, and add a custom condition class for special cases (JSON containment, full-text) rather than branching inside a controller. Decoupling input names from column names is the only gate stopping someone posting a filter against a field we never meant to expose.

The one-line version. Right tool, wrong framework for most of our stack — approve it as a routine patch where we already run Symfony, reimplement the pattern natively in Laravel, and do not let it become infrastructure.