Filter Widget Laravel Package

Getting Started

This is not a general-purpose filtering library. It is a widget bundle for Victoire DCMS — a Symfony 2/3-era CMS — that adds a "Filter" block you can drop onto a page so the rendered page lists a filtered set of Victoire BusinessEntity records. If you are not running Victoire, there is nothing here to use; evaluate doctrine/orm + a query builder directly instead.

Prerequisites (verify before you start):

• An existing Victoire DCMS install (VictoireCoreBundle and friends wired up in AppKernel).
• Symfony 2.8/3.x, PHP circa 5.6–7.0, Twig 1.x. The last tagged release is 2016-12-22; it will not install cleanly on modern Symfony without patches.
• Matching Victoire core version — the widget depends on Victoire's widget/filter abstractions, so pin it in composer.json against whatever Victoire version you run.

Minimal install:

composer require friendsofvictoire/filter-widget

// app/AppKernel.php
public function registerBundles()
{
    $bundles = [
        // ...
        new Victoire\Bundle\CoreBundle\VictoireCoreBundle(),
        new Victoire\Widget\FilterBundle\WidgetFilterBundle(), // confirm namespace from composer.json autoload / bundle class
    ];
}

Then:

app/console cache:clear
app/console doctrine:schema:update --dump-sql   # inspect before --force
app/console debug:container | grep -i widget   # see how the widget is registered

Where to look first, in this order:

1. README.md and composer.json — the required Victoire/Symfony version range is the whole story here. Confirm the bundle class namespace before writing AppKernel code.
2. Widget/ (or Entity/) — the widget entity itself. This tells you exactly which fields hold the filter criteria and what getWidgetName() returns.
3. Resources/views/ — the front-end Twig template you will almost certainly override.
4. Resources/config/ — service definitions and the widget tag; this is where you see what the filter widget delegates to (Victoire's business-entity filter service).
5. DependencyInjection/ — confirm there is no configuration you need to supply.

First use case: log into the Victoire back office, edit a page, insert the Filter widget into a slot, choose the target BusinessEntity (e.g. Article, Product), add criteria, publish, and see the filtered list render on the front end.

Implementation Patterns

Configure in the CMS, not in code. The intended workflow is: the editor picks the business entity and the conditions in the widget form; the widget serializes that configuration onto the widget entity; the front-end template resolves it against the query builder on render. Treat the stored widget configuration as user data, not as a config file.

Override the template — don't fork the bundle. The highest-leverage change is almost always presentation. Copy the widget's Twig template into your app's override path and edit it:

{# app/Resources/WidgetFilterBundle/views/Widget/show.html.twig #}
{# verify the exact subpath against Resources/views in the package #}
{% extends 'VictoireWidgetFilterBundle:Widget:show.html.twig' %}

{% block content %}
    <ul class="results">
        {% for item in filteredBusinessEntities %}
            <li><a href="{{ path('victoire_core_page_show', pathVariables) }}">{{ item }}</a></li>
        {% endfor %}
    </ul>
{% endblock %}

Inspect the shipped template first for the real variable names exposed by the widget — do not assume filteredBusinessEntities.

Reuse the filter service outside the widget. When you need the same filtering on a custom controller or a REST endpoint, inject the Victoire filter service directly rather than going through the widget:

// services.yml
my.service:
    class: AppBundle\Service\ProductLister
    arguments: ['@victoire.business_entity.filter'] # confirm service id from Resources/config

// in the service
$queryBuilder = $this->filter->buildQueryBuilder($businessEntityName, $criteria);
$queryBuilder->setMaxResults(20)->addOrderBy('e.createdAt', 'DESC');

This is the intended escape hatch: the widget is a thin UI over a filter abstraction, so most real work happens in your BusinessEntity class and the filter service.

Add a new criterion type by implementing Victoire's filter interface and tagging the service. That is the cleanest extension point — you keep the widget as-is and gain a new operator/field type for editors. Copy an existing filter class from vendor/victoire/ as the template.

Sort/paginate downstream. The widget gives you a filtered result set; it does not give you a pager. Attach KnpPaginator or a Pagerfanta adapter to the query builder and render the pager in your overridden template.

Theme/translation awareness. Widget content and labels are translatable in Victoire. Keep any new strings in the widget's translation domain rather than hardcoding them in the Twig override, otherwise multilingual pages drift.

Gotchas and Tips

• This is effectively frozen software. Three stars, zero dependents, last release December 2016. Budget time to read the source — there is no meaningful documentation surface. Fork it into vendor replacements (repositories in composer.json) rather than hoping for upstream fixes.
• Version lock-step. Widget bundles and Victoire core must match. A composer solve that picks a mismatched core will fail at runtime in confusing ways (missing widget tag, unknown parent class). Pin both explicitly.
• Schema changes are yours to make. Widget configuration lives in Doctrine entities. After install — and after any fork-level field addition — run doctrine:schema:update --dump-sql and review before --force. Victoire widget entities commonly share inheritance strategies; a careless update can touch more tables than you expect.
• Renaming a business entity property silently breaks stored filters. The criteria are persisted as field names on the widget record. A refactor of your entity means migrating the widget rows (write a Doctrine migration that rewrites the serialized/JSON criteria).
• Caching will make you doubt your changes. Victoire caches widget rendering and the widget map aggressively. After any template or bundle change: app/console cache:clear --env=dev plus a hard browser refresh. If the widget "disappears" from the picker, it is usually a stale cache or a missing/failed service tag — check debug:container and debug:event-dispatcher.
• Debugging order of operations: (1) is the widget registered and visible in the back office? (2) does the widget entity persist the criteria you chose? (3) does the filter service return the query builder you expect (dump() it in the template or a listener)? (4) is the Twig override actually being picked up (add a marker comment)? Each stage fails independently.
• Performance trap: the widget rebuilds its query on every page render, with no built-in result caching. On large tables without indexes on your filter columns, this is the slowest thing on the page. Add indexes on the fields editors are likely to filter by, and consider caching the rendered widget for anonymous traffic.
• i18n and permissions are per-widget. Victoire applies widget translation and role-based visibility at the widget level. If a filter shows the wrong language or leaks to anonymous users, the problem is in the widget record's translation/role config, not in this bundle.
• Extension points, ranked: template override (safest) → custom filter class + tag → injecting the filter service into your own service → subclassing the widget (most brittle, since you inherit its Symfony 2-era assumptions). Prefer the first three.
• Sanity check before committing to it: confirm the package installs against your Symfony/PHP combination and that the widget class autoloads. If either fails, stop — a 2016 bundle patched onto a modern stack will cost more than implementing the equivalent list widget yourself in a day.