Cover Widget Laravel Package

Getting Started

This is a Symfony bundle (not Laravel) — a widget plugin for the Victoire CMS. It renders a full-width "cover" block (background image + title/subtitle/CTA) that editors drop into pages from Victoire's front-end editor. Because it has zero dependents and its last release was April 2019, treat it as a reference implementation rather than a maintained dependency.

Minimal steps:

1. Install into a Victoire-enabled Symfony app (Symfony 3.x–4.x era). It will not install standalone and has no Laravel equivalent.

   composer require victoire/cover-widget
   

2. Register the bundle — AppKernel::registerBundles() (Symfony ≤3.4) or config/bundles.php (Symfony 4):

   new Victoire\Widget\CoverBundle\VictoireWidgetCoverBundle(),
   

3. Clear cache so Victoire picks up the widget registration:

   bin/console cache:clear
   

4. Open a page in the Victoire editor and look for Cover in the widget picker.

Where to look first:

• src/Widget/CoverWidget.php — the widget class: getName(), getCategory(), and the form fields it exposes (image, title, subtitle, link/CTA, CSS class).
• Resources/views/Widget/ — the Twig template that actually renders the block.
• Resources/config/ — service definitions and any widget registration metadata.
• composer.json — pin the Victoire core version it was tested against; this is the single biggest compatibility signal.

First use case: a marketing/homepage hero block. Drop a Cover into a page layout, upload a background image, set a title and CTA link, publish, and verify the front-end rendering.

Implementation Patterns

Editor-first usage. The intended workflow is almost entirely through Victoire's WYSIWYG editor — you configure the widget via its auto-generated form and rarely touch PHP. For day-to-day work, that means your job is theming and template overrides, not business logic.

Overriding the template. Standard Symfony bundle-override convention: copy Resources/views/Widget/cover.html.twig into app/Resources/VictoireWidgetCoverBundle/views/Widget/cover.html.twig (Symfony 3) or templates/bundles/VictoireWidgetCoverBundle/... (Symfony 4). Change markup and CSS classes there instead of forking the bundle.

Extending the widget with extra fields. Subclass CoverWidget (or copy it), add a form field in the widget's buildForm, persist it through the widget's business entity, and update the template. Register your subclass as the widget Victoire resolves for the cover name so the editor keeps working.

Programmatic rendering. When you already have a widget instance (e.g. seeded from a fixture, or fetched from WidgetRepository), render it with the registered template rather than reimplementing the markup:

{{ render_widget(coverWidget) }}

or include the bundle template directly and pass the same variables the widget exposes. Prefer this over hard-coding HTML so editor changes and template overrides stay in sync.

Theming / asset pipeline. Cover images typically go through Victoire's/your app's image resolver (LiipImagine or similar). Wire the thumbnail/full-size filters in config and reference them from the overridden template; don't hard-code raw upload paths.

Migration from a Symfony app. If you're porting this concept to Laravel, the closest analogue is a Blade component (<x-cover :image :title :cta />) backed by a database row for page blocks — the bundle's real value is its field schema and template structure, not its code.

Gotchas and Tips

• Abandoned and version-locked. Last release 2019, ~2 stars, no dependents. Expect Symfony 3/4 assumptions, old annotation-based service/route config, and possible deprecations under modern PHP. Do a composer why-not check against your Victoire core before committing.
• It is not standalone. The bundle assumes Victoire's WidgetBundle model, AbstractWidget, editor JS, and asset handling are present. Any attempt to use it outside Victoire (let alone Laravel/Symfony without the CMS) will fail at container build time.
• Cache is the #1 debugging trap. New widgets and template overrides don't appear until you clear the cache (bin/console cache:clear) and often hard-refresh the editor. If a widget is missing from the picker, check the bundle registration and cache before anything else.
• Template override path is version-sensitive. Symfony 3 uses app/Resources/<BundleName>/views/...; Symfony 4 uses templates/bundles/<BundleName>/.... Wrong path = silent fallback to the bundle's template, which looks like "my changes don't apply."
• Bundle name ≠ package name. The Composer package is victoire/cover-widget but the PHP bundle is VictoireWidgetCoverBundle. Use the bundle name for the override directory and container registration, the package name for composer.
• Editor vs. front rendering can diverge. The WYSIWYG editor may render a simplified preview template while the front end uses the full one. Test both — a style that looks right in the editor can break on the published page.
• Form field persistence is manual. If you add fields to the widget, remember the widget entity/schema must actually store them; a field that shows in the form but isn't persisted silently vanishes on save.
• Image handling is the main performance risk. Cover blocks are hero images. Configure responsive/compressed filters and loading="lazy" in your override; otherwise you ship a multi-MB hero on every page.
• Extension point for real work: fork or subclass the widget class rather than patching vendor/. Keep your version as a path/VCS Composer dependency so it survives composer update.