Html Widget Laravel Package

Getting Started

This bundle is an add-on for Victoire DCMS (a Symfony-based page-builder CMS), not a standalone package. It adds an "HTML" widget so editors can drop raw markup into a page zone.

Minimal steps:

1. Install Victoire DCMS first. This bundle is meaningless without the core widget infrastructure.
2. composer require friendsofvictoire/html-widget (verify the exact Packagist name — the repo is WidgetHtmlBundle, which often maps to a different composer name).
3. Register FriendsOfVictoire\WidgetHtmlBundle\WidgetHtmlBundle in config/bundles.php (or AppKernel on older Symfony).
4. Clear cache (bin/console cache:clear) and warm it, then open a page in the Victoire editor and look for the HTML widget in the widget picker.

Where to look first:

• src/Widget/ — the widget class. This defines the name, category, icon, and any form fields.
• Resources/views/ — the Twig template that actually renders the widget (this is where the |raw output lives).
• Resources/config/services.yml — the service tag that makes Victoire discover the widget.

First use case: open a page in the builder, drag the HTML widget into a zone, paste an embed (iframe, third-party snippet, custom markup), save, publish, and confirm it renders on the front end.

Implementation Patterns

Treat it as an embed widget, not a layout tool. The useful day-to-day pattern is dropping in iframes (maps, videos), third-party script snippets, or one-off markup that doesn't justify its own structured widget. For anything reused across pages, build a proper Victoire widget instead.

Service registration is the integration point. Victoire discovers widgets via a tagged service. If the bundle autoloads its services (Symfony 4+ services.yml convention), there is usually nothing to configure. If not, check the tag name against Victoire's docs for the version you run and register it explicitly.

Content field access. The widget entity typically exposes a single field (html, content, or similar). In the template it is read via the widget object — confirm the exact property by dumping the widget in the template ({{ dump(widget) }} with the profiler on) rather than guessing.

Overriding the template. Copy the bundle's template into your app (templates/bundles/WidgetHtmlBundle/... on Symfony 4+, app/Resources/... on older) and adjust it. This is the cleanest extension point for adding a wrapper <div>, scoping classes, or applying a sanitizer filter.

Sanitization pattern. If editors are untrusted, do not rely on the widget. Either:

• Restrict the widget to a trusted role via Victoire's permissions, or
• Pipe the output through an allowlist filter in an overridden template ({{ widget.html|purify }} if you have an HTMLPurifier Twig extension), or
• Decorate/replace the widget renderer service.

Composition workflow. HTML widgets live inside zones. Keep snippets self-contained: no global IDs, no assumptions about surrounding markup, responsive iframes (width="100%"), and CSS scoped to a wrapper class you control in the overridden template.

Fork-and-extend pattern. Because the package has no community traction, plan to fork it. Add fields (title, wrapper class), add sanitization, or convert it into a reusable "embed" widget with a provider dropdown. The widget class is small — extending it is faster than waiting for upstream.

Gotchas and Tips

• Abandonment risk is real. Zero stars/dependents means no issue triage and no compatibility guarantees. Vendor or fork the code, pin the version in composer.json, and check its Symfony/Victoire constraints before requiring it.
• Twig autoescaping will surprise you. Raw HTML only renders if the template uses |raw. If markup appears as literal text, that is the cause. Conversely, |raw is an XSS vector — see permissions above.
• CSP and script tags. Inline <script> in the widget may be blocked by your Content-Security-Policy, or stripped by whatever sanitizer the editor applies. Embeds often need a nonce or an external JS include instead.
• AJAX-rendered zones. If Victoire re-renders a zone via AJAX, scripts inside the widget will not execute (same as any dynamically injected script). Prefer declarative embeds.
• Caching. Victoire caches rendered pages aggressively. Edits not showing up usually means a stale cache or an unpublished revision — clear the cache and republish before debugging the widget.
• Widget missing from the picker. Almost always a service-tag or bundle-registration problem, not a template problem. Verify the tag matches the Victoire core version and that the cache was warmed after registration.
• Bundle registration differences. Symfony 4+ uses config/bundles.php; older projects use AppKernel. The package may predate the modern convention — check its composer.json symfony/* constraints.
• Template override path shifts by Symfony version. Use templates/bundles/WidgetHtmlBundle/ on modern Symfony; the old app/Resources/ path will silently do nothing on Symfony 4+.
• Duplicate DOM IDs. Editors pasting the same snippet on multiple pages or zones will produce duplicate IDs. Enforce a wrapper class and avoid IDs in snippets.
• Debugging tip. Use the Symfony profiler's Twig panel to inspect the actual variables passed to the widget template; dump the widget entity there rather than reading source, since the package's field names may differ from what you expect.