Weave Code
Filter Bundle Laravel Package
pugx/filter-bundle
PUGXFilterBundle brings annotation-driven filtering to Symfony and Doctrine: mark filterable entity fields, then render a form that automatically builds DQL queries from user input, giving you searchable, sortable list pages without hand-writing query logic.
PugxFilterBundle adds annotation-driven filtering to Doctrine entities in Symfony applications. Define filterable fields with @Filter annotations and let the bundle build reusable query filters, reducing boilerplate in repositories and controllers.
- Declarative annotation-based filter definitions
- Integrates with Doctrine ORM and Symfony’s service container
- Supports multiple filter types and custom filter logic
- Keeps filtering reusable across repositories and controllers
- Lightweight setup via bundle registration and configuration
Frequently asked questions about Filter Bundle
- Is pugx/filter-bundle compatible with Laravel?
- No. PUGXFilterBundle is a Symfony bundle built around Symfony's bundle and DI extension model, the Symfony Form component, Doctrine ORM entity metadata, and the kernel event system. None of those map onto Laravel's service-provider, Eloquent, or HTTP kernel model, and there is no facade, config bridge, or supported installation path into a Laravel application. Treat it as out of scope for a Laravel codebase rather than something that needs an adapter.
- What happens if I install pugx/filter-bundle in a Laravel app with Composer?
- Composer may resolve the dependency, but Laravel's package discovery will not register a Symfony bundle, so nothing gets bootstrapped. You would have to hand-write a bridge that boots the bundle, wires the Symfony Form factory, and integrates Doctrine metadata, which is far more work than the filtering feature is worth. The effort would exceed the cost of a native Laravel filtering library.
- What should Laravel developers use instead of pugx/filter-bundle for filtering queries?
- For Eloquent, the common choices are Spatie Laravel Query Builder for request-driven filtering, sorting, and includes, or Eloquent Filter packages that map query-string parameters onto model scopes. A small in-house filter abstraction built on query scopes is also a reasonable option and avoids locking into a third-party API. All three keep filtering logic out of controllers, which is the actual need PUGXFilterBundle serves on the Symfony side.
- What does PUGXFilterBundle do and when should I use it?
- It provides reusable, form-driven filtering and sorting for Symfony applications backed by Doctrine entities. You define a filter form type once, bind it to request parameters, and it composes query conditions for searchable lists and admin grids without duplicating filtering logic in controllers. It is a good fit for Symfony and Doctrine services that want declarative filter sets rather than hand-rolled query building.
- How do I install and configure PUGXFilterBundle in a Symfony application?
- Add it with Composer, register the bundle in your bundles.php or config/bundles.php, then create filter form types that map fields to your entity properties. You bind the filter form to the request and use the resulting filter object to build or modify a Doctrine query. Upgrading from 1.7.0 to 1.7.1 requires no configuration or code changes.
- What changed in pugx/filter-bundle 1.7.1 and do I need to change my code?
- Version 1.7.1 contains a single behavioral change: filter forms are now keyed by name instead of by positional index, and form state is reset between requests. There are no new features, no deprecations, and no public API changes, so it is a drop-in from 1.7.0. The only code at risk is anything that reached into the filter collection by ordinal position rather than by name.
- Is PUGXFilterBundle safe to use with long-running workers like FrankenPHP worker mode or RoadRunner?
- The 1.7.1 fix that resets filter forms between requests suggests the library previously assumed a classic PHP-FPM request lifecycle. On long-lived workers, per-request state hygiene should be treated as an active risk area to verify with your own tests rather than a solved problem. This is the same class of state-bleed bug that Laravel Octane teams regularly fight.
- Which PHP, Symfony, and Doctrine ORM versions does PUGXFilterBundle support?
- Check the composer.json constraints on the repository and Packagist for the exact supported matrix before pinning, since the bundle tracks Symfony Form and Doctrine ORM releases. A recurring breakage source is version skew between Doctrine ORM 2 and 3 and the switch from annotations to attributes. Confirm your pinned Symfony and Doctrine versions fall inside the supported range before adopting.
- How do I test filters built with PUGXFilterBundle?
- Unit test your filter form types by submitting data and asserting the resulting filter object exposes the expected values. For integration coverage, submit the filter form with query parameters and assert the generated query builder or returned result set matches expectations. Because state is now reset per request, include a test that runs two sequential filter submissions in one process to confirm no bleed-through.
- Is PUGXFilterBundle actively maintained, and is it a risky dependency?
- The project has a small maintainer footprint and low release cadence, and it reads as mature rather than actively expanding, with no vendor SLA behind it. That makes it a reasonable, narrowly scoped dependency for a Symfony service but not something to build a critical abstraction on top of without pinning versions. If your team owns no Symfony or Doctrine services, the maintenance question is moot because the package should not enter your stack at all.
Weaver
How can I help you explore Laravel packages today?