Cover Widget Laravel Package

Getting Started

Before anything else: this is not a Laravel package. It is a Symfony bundle for Victoire DCMS, a page-builder CMS built on Symfony. There is no service provider, no facade, no config file you can publish into config/. If your stack is Laravel, composer require friendsofvictoire/cover-widget will get you a bundle that does nothing — treat it as reference code to port, not a dependency to install.

Assuming a Victoire 2.x site on Symfony 3.4/4.x:

1. composer require friendsofvictoire/cover-widget
2. Register the bundle — new Victoire\Widget\CoverBundle\VictoireWidgetCoverBundle() in app/AppKernel.php, or the same class in config/bundles.php on Flex.
3. Victoire widgets are discovered through the victoire_widget DI tag. Confirm the bundle's Resources/config/services.yml (or DependencyInjection/) applies the tag; if the widget never shows in the editor, this is almost always the reason.
4. Widgets add their own Doctrine tables. Run doctrine:schema:update --force (or generate a migration) before opening the editor.
5. Open a page in the Victoire editor, drop the Cover widget into a slot, set the background image / heading / subtitle / CTA, save, publish.

Where to look first, in order of usefulness:

• Resources/views/show.html.twig — the front-end markup. This is what you will override 90% of the time.
• Form/WidgetCoverType.php — the exact list of editable fields. Anything not here is not editable by content authors without a fork.
• Widget/ or Entity/ — how the widget persists its values, and whether it has a translation entity.
• Resources/config/services.yml — tag, form type wiring, template resolver.

Realistic first use case: a full-bleed hero at the top of a landing page template — background image, overlay, headline, subtitle, one or two buttons. It is a small, single-purpose widget; expect to style it heavily and extend it lightly.

Implementation Patterns

Render it through Victoire, not directly. Widgets are rendered by the CMS's renderer into slots, not by including the bundle template yourself. Hand-including show.html.twig bypasses the slot context (widget, businessEntity, view/layout variables) and will break as soon as someone changes the template.

Override, don't edit vendor. Use Symfony's bundle template override path — templates/bundles/VictoireWidgetCoverBundle/show.html.twig on Symfony 4+, app/Resources/VictoireWidgetCoverBundle/views/ on Symfony 3. Keep the override to markup and class names; push all styling into your theme's stylesheet so a composer update never touches your design.

Extend the form type for extra fields (video background, gradient overlay, CTA style variants). Subclass WidgetCoverType, use getParent(), add your fields, and register your own widget class reusing the bundle's template. This keeps you on the same persistence table while giving authors richer controls. Be aware: changing the form type after content is already saved can orphan serialized values — plan field names up front and keep them additive.

Pin widgets in business templates. For pages where the cover must always be present (home, landing pages), define it in a Victoire business template slot rather than letting editors add/remove it ad hoc. Combine with the widget style/CSS-class picker so authors can pick a variant without touching structure.

Keep the Twig thin and the component thick. The bundle gives you markup; your theme should own the responsive behavior via CSS custom properties (--cover-height, --cover-overlay) so per-page variation doesn't require template forks. If you need computed values (responsive image srcset from a media reference), put that in a small Twig extension rather than inline in the widget template.

Check for i18n before promising it. Victoire widgets are only translatable if the bundle ships a translation entity (KnpDoctrineBehaviors style) or you wire one. Verify in Entity/ before telling content authors it's multilingual.

Laravel port pattern: the shape maps cleanly to an x-cover Blade component with @props(['image', 'title', 'subtitle', 'cta']) plus a Filament block or Nova field for the editor, and a mediable/spatie/laravel-medialibrary conversion for the background. The bundle is a good checklist of what fields authors actually want; copy the field list, not the code.

Gotchas and Tips

• Zero stars, zero dependents is the headline risk. Treat this as sample code from the FriendsOfVictoire org, not a maintained dependency. Fork it into your own VCS, pin the exact version, and expect to own it. Check composer.json's Symfony constraint against your project before installing — these bundles often lag well behind current Symfony.
• Widget invisible in the editor: in order of likelihood — bundle not registered, victoire_widget tag missing, widget class not implementing the expected identifier/name contract, or cache not cleared. bin/console debug:container --tag=victoire_widget settles it.
• Schema drift: widget tables are created by Doctrine, not by the bundle's install. Forgetting the migration step produces silent save failures in the editor.
• Cache everywhere. Victoire caches rendered pages; Twig and form-type changes commonly need cache:clear before they appear. If a template override "does nothing," it's the cache far more often than the path.
• Assets. If the widget ships its own CSS/JS, remember assets:install / your Webpack step. A cover that renders unstyled is usually an unpublished asset, not broken markup.
• Debugging form save: dump the widget entity after submit. Victoire's widget form pipeline swallows a lot; the persisted values tell you immediately whether the problem is the form type, the entity mapping, or the template.
• Extension points worth knowing: template override (cheap, safe), FormType inheritance (medium, watch persistence compatibility), custom widget bundle (heavy but cleanest for a heavily customized hero), and a Twig extension for computed media values. There is no plugin/hook system beyond these — you are extending Symfony, not the bundle.
• Don't over-invest. For a single hero section, the cost of adopting and maintaining an abandoned Symfony bundle in a Laravel shop is far higher than writing a 40-line Blade component. Use this repo as a spec for fields and authoring UX, and build the thing yourself.