Layout Widget Laravel Package

Getting Started

This is not a standalone layout library — it is a Victoire CMS widget that adds a "Layout" element (columns/rows container) to the Victoire page builder so editors can nest other widgets inside slots. It is only useful inside an existing Victoire application; installing it in a plain Symfony app gives you a bundle with no route, no UI, and no purpose.

Steps:

1. Confirm you are on a Victoire CMS app (Symfony 2.8/3.x era, victoire/core-bundle + victoire/widget-bundle present). Check composer show | grep victoire.
2. composer require victoire/layout-widget — pin the exact released version afterwards. Expect PHP/Symfony constraint friction on modern stacks; run it under the PHP version your Victoire install already targets (5.6/7.0/7.1).
3. Register the bundle in app/AppKernel.php (new Victoire\Widget\LayoutBundle\VictoireWidgetLayoutBundle() — confirm the class name in vendor/victoire/layout-widget/*Bundle.php), then bin/console cache:clear.
4. Where to look first, in vendor/victoire/layout-widget/:
   • Entity/ — the widget model and its stored options (column scheme, etc.)
   • Form/ — the editor-facing form (layout picker)
   • Resources/views/ — the show.html.twig templates, one per layout variant
   • Resources/config/ — service/tag registration that makes the widget appear in the picker
5. First use case: open a page in the Victoire editor, drop a Layout widget in, pick a 2- or 3-column scheme, drop a Text widget into each slot, save, and verify the front-end render. If the widget doesn't appear in the picker, stop and fix registration before writing any code.

Implementation Patterns

Template override, not fork. Copy the bundle's views into your app and edit there: app/Resources/VictoireWidgetLayoutBundle/views/ (Symfony 2/3) or templates/bundles/VictoireWidgetLayoutBundle/ (newer). Victoire resolves the app-level template first, so overrides survive composer update.

Adding a layout variant. Three coordinated edits: add the choice to the layout picker in the form type (or via a form extension), add a Twig template matching the chosen key, and keep the slot-render calls identical to the existing templates — reuse the bundle's own Victoire slot/render helper verbatim rather than inventing one. Register the new template/key in the same place the bundle's existing variants are registered.

Slot names are the contract. Slots are referenced by name in Twig and the widget tree is stored in the database. Adding a fourth slot to an existing scheme is safe; renaming or removing one silently orphans editor content. Treat slot names as schema.

Nesting discipline. The layout widget is a container, so it composes by nesting any other Victoire widget. Keep nesting shallow (layout → content widgets, not layout → layout → layout): every nested widget is another DB lookup and render pass, and deep nesting makes editorial output and debugging painful.

Theming at the page level. Layouts are structural. Put grid/flex CSS on the layout classes in your app stylesheet rather than overriding markup, and use the template override only when the emitted wrapper structure genuinely blocks your design (e.g., switching to CSS Grid or adding responsive breakpoints).

Subclass/extend for per-layout options. If you need background color, container width, or spacing per layout, extend the widget's form with a FormTypeExtension and add the fields in your overridden template. This keeps the upstream entity untouched and upgradeable.

Programmatic/fixture creation. When seeding pages, create the layout widget entity, set its layout option, and attach child widgets through Victoire's widget manager rather than hand-writing rows — then render via the widget renderer so CLI/CI output matches the front end.

Gotchas and Tips

• Unmaintained, near-zero adoption. Last release 2016, 2 stars, 0 dependents. Budget for vendoring or forking. Before committing, diff it against the Victoire version you run; if it breaks on upgrade, lift the templates into your app and drop the bundle.
• Registration is the usual failure. Widget missing from the editor picker almost always means the service tag/compiler pass didn't pick it up, the bundle isn't enabled, or cache is stale. cache:clear and confirm the service is tagged in debug:container.
• Caching bites nested renders. Victoire caches widget output; after a template override you may still see the old markup. Clear cache and check whether the widget renders through an ESI/subrequest — the profiler shows subrequests separately, which is where nested-render bugs hide.
• Debug nested widgets via the request stack. {{ dump() }} plus the profiler's subrequest panel is faster than guessing; exceptions inside a slot can surface as a blank column rather than an error page.
• Override path is Symfony-version-specific. Wrong directory = silent no-op, not an error. Verify by adding an obvious HTML comment to the override and reloading.
• Escaping. Layouts render editor-supplied content; |raw is often required for widget HTML. Make sure anything editor-controlled is sanitized and that only trusted roles can edit layouts.
• Accessibility/responsive defaults are dated. The original markup is fixed-column; expect to override for CSS Grid, semantic landmarks, and mobile breakpoints.
• No meaningful upstream test suite. Write your own smoke test (render a page containing a layout with one child widget, assert both appear) and run it against a real Victoire app — isolated unit tests are largely impractical here.