Image Widget Laravel Package

Getting Started

This is the image widget for Victoire DCMS, a Symfony-based CMS. Before anything else, confirm you are actually running Victoire — the bundle is useless standalone, and the ecosystem is effectively dormant (0 stars, 0 dependents, no recent activity). Treat it as legacy code you are inheriting, not a package you are adopting.

Minimal steps:

composer require friendsofvictoire/image-widget

Then register it in app/AppKernel.php (Symfony 2/3 era) alongside Victoire itself:

$bundles = [
    new Victoire\Bundle\CoreBundle\VictoireCoreBundle(),
    new FriendsOfVictoire\Widget\ImageBundle\WidgetImageBundle(),
];

Match the constraint against your Victoire version — the bundle was built for a specific Symfony major (2.8/3.x). If Composer resolves to a Symfony 4+ app, stop; it will not boot.

Where to look first, in this order:

1. Widget/ — the widget class (likely ImageWidget) extending Victoire's BaseWidget. This is the contract: what fields exist, what the business entity stores.
2. Resources/config/services.yml — the victoire.widget service tag and its name/category attributes. This is what makes the widget appear in the editor palette.
3. Resources/views/ — the front-end Twig template. This is what you will override 90% of the time.
4. Form/ — the Symfony form type that drives the authoring UI in the Victoire editor.

First use case: drop an image into a Victoire page slot from the editor UI, confirm it renders, then immediately override the front-end template to output alt, title, and a srcset — the default template almost certainly predates responsive images.

Implementation Patterns

Template override (the primary workflow). Never edit the vendor bundle. Override via the standard Symfony path, which for this bundle is:

app/Resources/FriendsOfVictoireWidgetImageBundle/views/Widget/imageWidget.html.twig

Copy the vendor template, adjust markup, keep the same variable names (widget, image, businessEntity). Clear cache after every override — Victoire caches aggressively and a stale template override is the single most common "my change did nothing" bug.

Adding fields. Extend the widget's entity/form rather than forking. The pattern is: add a property to the entity, add the field in the Form/ type, expose it in the template. If the bundle's entity is not designed for extension, use a Doctrine inheritance or a listener on post-load to attach computed values (e.g. a caption pulled from media metadata) instead of modifying the vendor class.

Reusable presentation logic. Put image URL derivation and srcset generation in a Twig extension or a small service, not in the widget template. Victoire pages are assembled from many widgets; duplicated media logic across templates rots fast.

Integration with LiipImagineBundle. Most Victoire image setups use Liip filters. Resolve URLs through the imagine_filter Twig filter (or liip_imagine.cache.manager) in the template, and define named filters (widget_thumb, widget_hero) per breakpoint. This keeps the widget entity storing an original asset while the template decides rendition.

Rendering outside the editor. Widgets can be rendered programmatically for API/headless use:

{{ victoire_widget_render(widget) }}

or by resolving the widget service and calling its render method. Useful when you need the same image markup in a newsletter or mobile endpoint. Keep the business entity and the presentation template decoupled so this remains possible.

Composition with other widgets. Image widgets are usually paired with text/link widgets in a two-column slot. Do not hard-code layout in the image template — use the slot/container structure Victoire provides, and let CSS own the grid.

Gotchas and Tips

• Maintenance risk is the headline. Zero stars, zero dependents, and the parent Victoire project is stagnant. Pin the exact version in composer.json, commit composer.lock, and plan for a fork if you need long-term support. There will be no upstream fixes.
• Service visibility. On newer Symfony versions, services registered by the bundle may be private, breaking the widget tag resolution. If the widget doesn't appear in the palette, check services.yml for public: true on the widget service — this is the classic Victoire-on-modern-Symfony failure.
• Cache is the default suspect. After template overrides, config changes, or translation edits: php app/console cache:clear --env=dev (and again for prod). Victoire's editor also caches widget definitions.
• Translations. The bundle originates from a French project. Check Resources/translations/ for the translation domain and expect French strings as defaults. Add your locale's file rather than editing vendor translations.
• Asset paths vs. CMS-stored files. Images uploaded through Victoire's media manager live under web/uploads/ (or a configured adapter), not web/bundles/. Do not use asset() blindly on stored paths — resolve through the media/asset helper the bundle provides, or the image 404s in prod after a deploy that doesn't rsync uploads.
• Alt text is not guaranteed. Assume the default template omits or empties alt. Audit and enforce it; accessibility debt in CMS widgets is invisible until an audit.
• Debugging the editor. If the form doesn't save, dump the widget service in a controller ($container->get('...')) and inspect the entity after submit. The Victoire editor swallows form errors behind a generic JS toast — check the Symfony profiler's form panel, not the UI.
• Extension point: the cleanest long-term move is to subclass the widget, register your own victoire.widget service tag, and leave the vendor bundle as a dependency of your own AppWidgetImageBundle. Then upstream breakage is isolated to one file you control.