Listing Widget Laravel Package

Getting Started

Reality check before anything else: friendsofvictoire/listing-widget is not a Laravel package. It is a Symfony bundle (FriendsOfVictoire/WidgetListingBundle) that provides a "Listing" widget for Victoire DCMS, an open-source Symfony CMS. If you are on Laravel, there is no adapter, no service provider, and no Blade integration — you cannot use this package meaningfully in a Laravel app. It is only relevant if you are maintaining a legacy Symfony 2.8/3.x site built on Victoire.

Assuming you are in that situation:

1. Install into a Victoire-enabled Symfony app only. Victoire itself must already be installed and working; this bundle depends on Victoire\Bundle\WidgetBundle base classes.

   composer require friendsofvictoire/listing-widget
   

2. Register the bundle in app/AppKernel.php alongside the other Victoire\Widget\*Bundle entries (typically in the dev/prod bundles array, after Victoire core).
3. Clear cache and refresh the widget registry — Victoire discovers widgets at container compile time, so a stale cache is the #1 reason the widget does not appear.

   php app/console cache:clear --env=dev
   php app/console doctrine:schema:update --dump-sql   # new widget entity => new table/columns
   

4. Look here first, in this order:
   • Entity/WidgetListing.php — the Doctrine entity holding the widget's configuration (business entity target, max results, ordering, template choice).
   • Form/WidgetListingType.php — the editor-facing form; this tells you exactly which knobs the CMS user has.
   • Resources/views/.../show.html.twig — the front-end render; this is where you will do 90% of your customization.
   • Resources/config/ — service and widget registration.

First use case: open a page in Victoire's front-end edit mode, drag the "Listing" widget into a slot, pick the business entity to list, set the number/order of items, save, publish. That is the package's entire scope — a configurable entity list widget inside the page builder.

Implementation Patterns

Editor-driven configuration (the intended path). The widget is designed to be configured through the CMS UI, not code. Your job as a developer is usually to (a) make the business entity available/queryable, and (b) choose or override the template. Resist the urge to hardcode listing logic in PHP.

Template override — the main integration point. Override the widget's Twig template to control markup, wrapping, pagination, and item partials. In Victoire's convention this is done by placing your template at a higher-priority path (app-level Resources/ or a bundle that overrides this one) using the same relative template name, so Twig's loader resolves yours first. Keep the original as a reference and copy it before editing.

Data source pattern. The widget references a Victoire "business entity" (or a configured query) and renders a collection. Typical knobs exposed by listing-style widgets:

// illustrative shape — verify against the actual WidgetListing entity
$widget->setBusinessEntityId(...);
$widget->setMaxResults(10);
$widget->setOrderBy('createdAt');
$widget->setOrderDirection('DESC');
$widget->setTemplate('custom_list');

When you need filters the form doesn't expose, decorate the widget's rendering service or add a Twig extension rather than editing vendor code.

Programmatic creation (seeding / fixtures / imports). If you need to create listing widgets outside the UI — fixtures, content migrations, multi-site cloning — instantiate the WidgetListing entity, set its fields, persist it via Doctrine, then attach it to the page's WidgetMap/slot using Victoire's widget-map service. Always exercise this in dev first: widget maps have positional/slot semantics that are easy to corrupt, and a broken map can make the whole page fail to render.

Subclassing for reusable variants. If you repeatedly need "Listing + X", create a thin bundle whose widget entity extends WidgetListing, add the extra form fields, and register it as a distinct widget. This keeps the original untouched and gives editors a separate, clearly named widget.

Theming per site. For multi-site or multi-brand Victoire installs, map template names to per-site directories in the widget config so the same widget class renders differently per brand. This is cleaner than branching inside one template.

Testing. Cover it with a functional test that loads a published page containing the widget and asserts on rendered HTML — unit-testing the entity tells you nothing about whether the widget map, template resolution, and Doctrine query all line up.

Gotchas and Tips

• Abandoned since May 2019, 2 stars, 0 dependents. No security patches, no Symfony 4/5/6 support, no maintainer. Treat any adoption as "inherited legacy code," not "adding a dependency." Audit it and consider forking into your own vendor namespace so you control the fixes.
• Symfony-version lock-in. Victoire's widget base classes are Symfony 2.8/3.x era. This will not install cleanly on modern Symfony without patching composer.json constraints — and even then, Widget's API assumptions (Doctrine EntityManager, form types, Twig namespacing) may break.
• Schema drift. The widget entity extends the base Widget entity, so it participates in Doctrine inheritance. Adding the bundle requires a doctrine:schema:update (or a hand-written migration) — forgetting this yields cryptic "table not found" errors at render time, not at boot.
• Widget doesn't appear in the picker? In order: clear cache, confirm the bundle is registered, check the widget registration is loaded at container compile time, and confirm the widget's name/description translation keys resolve. A missing translation key can make it look absent rather than broken.
• Template resolution confusion. Victoire's Twig namespacing (WidgetListing:show.html.twig-style logical names) predates modern bundle path conventions. If your override "isn't taking," confirm the exact logical name from the original config rather than guessing the file path.
• Doctrine query cost. Listings render on every page load. Watch for N+1 when the template touches relations on each item — eager-load via the widget's query configuration or a repository method, not inside the Twig loop.
• Caching bites hard. Victoire caches pages and widget maps. After template, config, or entity changes, clear the app cache and any CMS-level page cache, or you will debug a problem that is already fixed.
• Debugging strategy. Reduce to a page with only this widget, dump the resolved WidgetListing instance in the template ({{ dump(widget) }} in dev), confirm the configured entity/limit/order are actually persisted, then confirm the query returns rows. Most "broken widget" reports are empty query results, not rendering bugs.
• Extension points that are safe: template overrides, a decorator service around the renderer, a Twig extension for custom formatting, and a subclass widget. Unsafe: editing files in vendor/ — you will lose them on the next composer install, and there will be no upstream release to carry your fix.
• Don't build new features on it. For anything greenfield, write the listing as a plain Symfony controller/Twig partial or evaluate a maintained CMS. This package's value is limited to not rewriting a widget in an existing Victoire install.