From a67764a82cc0134c466c882d82f1e6d5ca8e378e Mon Sep 17 00:00:00 2001 From: Gilles Gauthier Date: Thu, 1 Oct 2026 14:37:33 +0200 Subject: [PATCH 1/3] chore(docs): update README and installation requirements --- README.md | 24 +++++++++++++++++------- docs/guide/installation.md | 8 ++++++++ 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1bcbcc0..29b6bc2 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,6 @@ Build a Symfony form dedicated to filtering an entity, then let the bundle turn it into Doctrine ORM query builder conditions. -> `LexikFormFilterBundle` is now `SpiriitFormFilterBundle`: only the name and the GitHub organization -> changed, the code remains the same. - **📖 Full documentation: [spiriitlabs.github.io/form-filter-bundle](https://spiriitlabs.github.io/form-filter-bundle/)** The idea is: @@ -22,13 +19,25 @@ The idea is: Any type works, but filtering on a type other than a `XxxFilterType::class` requires a [custom listener](https://spiriitlabs.github.io/form-filter-bundle/features/working-with-the-bundle) to apply the filter. +## Why this bundle + +- **Plain Symfony forms**: no new DSL, your filters are regular form types with validation, theming and CSRF. +- **Ready-to-use filter types**: text, number, date and date range, boolean, choice, entity, enum and more. +- **Composable conditions**: AND/OR trees, embedded filters, collections and automatic joins. +- **Fully customisable**: override any field with a closure or a dedicated listener through `apply_filter`. +- **Debuggable**: the Symfony profiler shows which form field produced which DQL condition. + ## Installation ```bash composer require spiriitlabs/form-filter-bundle ``` -Requires PHP 8.1+ and Symfony 5.4+. For Symfony 2.8/3.4, use the latest `v5.*` tag. +| Requirement | Version | +|-------------|---------| +| PHP | 8.1+ | +| Symfony | 5.4, 6.4, 7.4, 8.0 | +| Doctrine ORM | 3.0+ | ## Use it in two steps @@ -81,18 +90,19 @@ class DefaultController extends AbstractController ## Documentation +- [Interactive demo](https://spiriitlabs.github.io/form-filter-bundle/guide/interactive-demo): follow a filter from form to DQL - [Installation](https://spiriitlabs.github.io/form-filter-bundle/guide/installation) - [Basics](https://spiriitlabs.github.io/form-filter-bundle/guide/basics) - [Configuration](https://spiriitlabs.github.io/form-filter-bundle/guide/configuration) - [Provided filter types](https://spiriitlabs.github.io/form-filter-bundle/features/provided-types) - [Filter state persistence](https://spiriitlabs.github.io/form-filter-bundle/features/persistence) - [Debugging & profiler](https://spiriitlabs.github.io/form-filter-bundle/features/debugging) +- [Pagination with Pagerfanta](https://spiriitlabs.github.io/form-filter-bundle/advanced/pagerfanta) ## Community support -Please [open a question on StackOverflow](http://stackoverflow.com/questions/ask) using the -[`spiriitformfilterbundle` tag](http://stackoverflow.com/questions/tagged/spiriitformfilterbundle), the -official support platform for this bundle. GitHub issues are dedicated to bug reports and feature requests. +Found a bug or missing a feature? [Open an issue](https://github.com/SpiriitLabs/form-filter-bundle/issues). +Questions are welcome there too. ## Credits diff --git a/docs/guide/installation.md b/docs/guide/installation.md index bd9cc0a..7942729 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -10,4 +10,12 @@ The bundle can be installed using Composer or the [Symfony binary](https://symfo composer require spiriitlabs/form-filter-bundle ``` +## Requirements + +| Requirement | Version | +|-------------|---------| +| PHP | 8.1+ | +| Symfony | 5.4, 6.4, 7.4, 8.0 | +| Doctrine ORM | 3.0+ | + Next: [Configuration](/guide/configuration) From 6898e19f2a10329a30ec6a48693255f52ce2ee5c Mon Sep 17 00:00:00 2001 From: Gilles Gauthier Date: Thu, 1 Oct 2026 14:38:11 +0200 Subject: [PATCH 2/3] chore(docs): add Turbo and Stimulus live filtering guide --- README.md | 1 + docs/.vitepress/config.mts | 1 + docs/advanced/turbo-stimulus.md | 98 +++++++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 docs/advanced/turbo-stimulus.md diff --git a/README.md b/README.md index 29b6bc2..e775034 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,7 @@ class DefaultController extends AbstractController - [Filter state persistence](https://spiriitlabs.github.io/form-filter-bundle/features/persistence) - [Debugging & profiler](https://spiriitlabs.github.io/form-filter-bundle/features/debugging) - [Pagination with Pagerfanta](https://spiriitlabs.github.io/form-filter-bundle/advanced/pagerfanta) +- [Live filtering with Turbo and Stimulus](https://spiriitlabs.github.io/form-filter-bundle/advanced/turbo-stimulus) ## Community support diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 76327d0..55bdea4 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -103,6 +103,7 @@ export default defineConfig({ items: [ { text: 'Working with other bundles', link: '/advanced/working-with-other-bundles' }, { text: 'Advanced usage with PagerFanta', link: '/advanced/pagerfanta' }, + { text: 'Live filtering with Turbo and Stimulus', link: '/advanced/turbo-stimulus' }, ], }, ], diff --git a/docs/advanced/turbo-stimulus.md b/docs/advanced/turbo-stimulus.md new file mode 100644 index 0000000..30f269c --- /dev/null +++ b/docs/advanced/turbo-stimulus.md @@ -0,0 +1,98 @@ +--- +description: Filter a list without reloading the page, using Symfony UX Turbo and a small Stimulus controller. +--- + +# Live filtering with Turbo and Stimulus + +A filter form is a plain GET form, which makes it a good fit for [Symfony UX Turbo](https://symfony.com/bundles/ux-turbo/current/index.html): the results are wrapped in a Turbo Frame, the form targets that frame, and only the results are refreshed. A tiny [Stimulus](https://symfony.com/bundles/StimulusBundle/current/index.html) controller submits the form while the user types. + +No JavaScript is needed for the frame itself, and without JavaScript the form still works as a regular page submission. + +```bash +composer require symfony/ux-turbo symfony/stimulus-bundle +``` + +## The controller + +The form must use the GET method so the filter ends up in the URL. Disable CSRF protection: a search form changes no state. + +```php +class UserListController extends AbstractController +{ + #[Route('/users', name: 'user_list')] + public function __invoke( + Request $request, + UserRepository $userRepository, + FilterBuilderUpdater $filterBuilderUpdater, + ): Response { + $form = $this->createForm(UserFilterType::class, null, [ + 'method' => Request::METHOD_GET, + 'csrf_protection' => false, + ]); + $form->handleRequest($request); + + $queryBuilder = $userRepository->createQueryBuilder('u'); + $filterBuilderUpdater->addFilterConditions($form, $queryBuilder); + + return $this->render('user/list.html.twig', [ + 'form' => $form, + 'users' => $queryBuilder->getQuery()->getResult(), + ]); + } +} +``` + +## The template + +The form lives outside the frame, so it is never re-rendered and keeps its focus while the user types. `data-turbo-frame` makes the submission target the results frame, and `data-turbo-action="advance"` pushes the filtered URL in the browser history, so a filtered list can be bookmarked and shared. + +```twig +{{ form_start(form, {attr: { + 'data-controller': 'filter-form', + 'data-action': 'input->filter-form#submit', + 'data-turbo-frame': 'results', + 'data-turbo-action': 'advance', +}}) }} + {{ form_widget(form) }} + +{{ form_end(form) }} + + +
    + {% for user in users %} +
  • {{ user.name }}
  • + {% endfor %} +
+
+``` + +Links inside the frame, such as pagination links, also navigate only the frame. Make sure they keep the current query string so the filter survives a page change. + +## The Stimulus controller + +Create `assets/controllers/filter_form_controller.js`. It waits for the user to stop typing before submitting the form: + +```js +import { Controller } from '@hotwired/stimulus'; + +export default class extends Controller { + static values = { delay: { type: Number, default: 300 } }; + + submit() { + clearTimeout(this.timeout); + this.timeout = setTimeout(() => this.element.requestSubmit(), this.delayValue); + } + + disconnect() { + clearTimeout(this.timeout); + } +} +``` + +`requestSubmit()` fires a real `submit` event, which Turbo intercepts, whereas `submit()` would bypass it and reload the whole page. + +To change the delay, add `'data-filter-form-delay-value': 500` to the form attributes. + +## Going further + +The same list can be wrapped in a [Twig component](/advanced/pagerfanta#bonus-twig-list-component) so the frame, the table and the pagination are reused across screens. From bc25f7ac9886759bd4d50200fa3901c4aa2c8976 Mon Sep 17 00:00:00 2001 From: Gilles Gauthier Date: Thu, 1 Oct 2026 14:49:51 +0200 Subject: [PATCH 3/3] chore(docs): clarify pagination query string in Turbo guide --- docs/advanced/turbo-stimulus.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/advanced/turbo-stimulus.md b/docs/advanced/turbo-stimulus.md index 30f269c..729d174 100644 --- a/docs/advanced/turbo-stimulus.md +++ b/docs/advanced/turbo-stimulus.md @@ -66,7 +66,11 @@ The form lives outside the frame, so it is never re-rendered and keeps its focus ``` -Links inside the frame, such as pagination links, also navigate only the frame. Make sure they keep the current query string so the filter survives a page change. +Links inside the frame, such as pagination links, also navigate only the frame. The `pagerfanta()` Twig function of [PagerfantaBundle](/advanced/pagerfanta) merges the current query string into every link it generates, so the filter survives a page change. For hand-written links, do the same: + +```twig +Next +``` ## The Stimulus controller