Text Widget Laravel Package

Getting Started

Framework check before anything else. friendsofvictoire/text-widget resolves to FriendsOfVictoire/WidgetTextBundle — a Symfony bundle for the Victoire CMS, not a Laravel package. There is no service provider, no Blade view, no Eloquent model, and no adapter path worth building. If you're in a Laravel codebase, the correct "getting started" is a one-day native reimplementation (migration + model + Blade component + admin field); use the bundle's Resources/views/Widget/Text.html.twig and Form/WidgetTextType.php as a specification only. Everything below assumes you are already inside a Victoire installation and need to work with the widget that exists.

Install (Victoire apps only):

composer require friendsofvictoire/text-widget

Register the bundle next to the rest of the Victoire bundle set:

// config/bundles.php (Flex) or AppKernel::registerBundles()
Victoire\Widget\TextBundle\VictoireWidgetTextBundle::class => ['all' => true],

Then sync the widget table and clear caches:

bin/console doctrine:schema:update --force
bin/console cache:clear

Where to look first, in order:

1. Entity/WidgetText.php — the persistent widget; extends Victoire\Bundle\WidgetBundle\Entity\Widget and inherits slot/position/page relationships. This is where your data shape lives.
2. Form/WidgetTextType.php — the admin form; typically a CKEditor-backed content field.
3. Resources/views/Widget/Text.html.twig — the front-end rendering template. The file you will override most often.
4. Resources/translations/ — the widget label and help text shown in the editor's widget picker.
5. The Victoire widget-manager configuration that registers the widget name/category.

First use case: open a Victoire business page or template in the editor, drag the "Text" widget into a slot, type content, save, and confirm it renders on the front end. If that round-trip works, installation is correct. If the widget doesn't appear in the picker, the bundle isn't registered (or the cache wasn't cleared) — not a template problem.

Debug entry points:

bin/console debug:container | grep -i widget
bin/console debug:twig | grep -i WidgetText
bin/console doctrine:mapping:info

Implementation Patterns

Template override as the default workflow. Do not edit the vendor file. In Symfony 4+/Flex, override at:

templates/bundles/VictoireWidgetTextBundle/Widget/Text.html.twig

In older Symfony 3-era apps the path is app/Resources/VictoireWidgetTextBundle/views/Widget/Text.html.twig. Clear cache after every override change — stale Twig cache is the most common "my template edit did nothing" cause.

Reuse through business templates, not per-page copies. The high-leverage pattern is to place the text widget once in a Victoire business template (layout) and let pages inherit it. That keeps a single render path and a single override point instead of N page-level copies that drift.

Subclass the widget when you outgrow a single body field. A very common day-to-day task is "we need a heading plus a body" or "we need an alignment choice." Rather than hacking the base entity, add a child bundle:

• Subclass WidgetText with the extra columns (a heading string, an alignment choice, etc.).
• Subclass WidgetTextType to add those fields.
• Register the new widget type with the Victoire widget manager alongside the original.
• Point the new widget at its own Twig template.

This keeps the vendor bundle untouched, so composer update (should it ever happen) doesn't conflict.

Form customization. For CKEditor tweaks — toolbar, allowed tags, height — change the field options in your form type subclass or configure the editor globally, not in the Twig template. Validation (max length, required body) belongs on the form type; putting it in the template produces inconsistent editor-side behavior versus programmatic saves.

Ordering and multiple instances. Each dropped text block is a separate WidgetText record with its own position within a slot. If you need deterministic ordering in a slot with mixed widget types, sort explicitly in the slot renderer rather than relying on insertion order — Victoire's position field is per-widget and can surprise you when widgets are dragged between slots.

Localization. Victoire handles per-locale widget instances; the text widget itself carries no locale logic of its own. If you add fields to a subclass, ensure content (or whatever you render) has a sane fallback so a missing translation doesn't render an empty <div> — do that in the template override with an explicit {% if %} guard, not a default filter that masks missing translations.

Styling. Wrap the widget output in a stable class in your override (e.g. .widget-text) so front-end CSS doesn't depend on Victoire's internal markup. This is the cheapest buffer against a future Victoire upgrade changing the wrapper structure.

Testing. Functional tests are worth the small effort here precisely because upstream has no test suite: boot the kernel, load a page fixture containing a WidgetText, and assert rendered output for content present / content empty / unknown locale. That's your only regression net.

Exit plan while you're already in it. Keep the template override and any entity subclass in your codebase, referencing vendor classes only through inheritance. That way, if you later replace the widget with an in-house component (the recommended trajectory given 0 stars and a dormant upstream), you swap the render path without touching page data.

Gotchas and Tips

This is not a Laravel package — do not attempt the bridge. Laravel vendors some Symfony components (HttpFoundation, Console, Process, Routing) but not symfony/http-kernel, the DI extension loader, framework-bundle, or Twig. Bridging means a second container, a Doctrine connection for widget storage, and a Twig bridge — all to render a title and a body. The commodity equivalent is roughly a day of Eloquent + Blade work.

Composer will likely fail before anything else does. The Victoire line is pinned to Symfony 2.x/3.x-era constraints, which are end-of-life. On PHP 8.2+ with Symfony 7 components, expect hard resolution conflicts on PHP constraints, symfony/* pins, Twig, and Doctrine ORM 2.x. If someone insists on evaluating integration, make composer require in a throwaway branch step zero — it's the cheapest possible go/no-go test and the answer will be no.

doctrine:schema:update --force is fine on a dev box, dangerous in production. The bundle ships its own entity mapping; on a real deployment, generate a Doctrine migration and review it, especially if the widget table already carries a different Victoire version's columns.

Cache is the answer to most "it's broken" reports. After a template override, a bundle registration change, or a translation edit: bin/console cache:clear. In dev, also check var/cache/dev/twig/ if you suspect a stale compiled template.

Template override path is version-sensitive. Symfony 3 apps use app/Resources/.../views/; Symfony 4+ uses templates/bundles/<BundleName>/.... Getting this wrong means your override is silently ignored — the vendor template renders and everything "looks fine."

Escape deliberately. The widget body is user-authored rich text; render it with |raw only because the editor pipeline is trusted. If you extend the widget to accept pasted HTML from untrusted roles, add a sanitizer in the form type — there is no filtering layer inherited from the bundle.

No maintainer means you own every defect. Zero stars, zero dependents, no issue activity, no Stack Overflow footprint, no docs beyond a README. Your escalation path for any bug is "read the source and patch it in a fork." Budget for that before adopting it in a second project.

Forks: scope them to templates and entity subclasses. The only genuinely reusable assets are the Twig templates and the field schema. Forking the PHP classes drags Victoire core bundles and Doctrine into your dependency graph for the sake of one content block.

Extension points that actually exist: subclassing the entity/form type, overriding the Twig template, translation files for editor-facing labels, and the Victoire widget-manager registration entry. Everything else is vendor code you should treat as read-only.

Hidden dependency risk. The bundle depends on Victoire core bundles by name. Confirm what composer why victoire/victoire pulls in on your install before assuming this is a "lightweight" addition — rendering one text block should not require the whole CMS in a fresh app.

Observability gap. Because you're inside a bridged/legacy path, logging and error reporting for widget rendering won't necessarily flow through your app's normal channels. If you must run this in production, wrap the render in your own template and log failures there — a silent empty div is worse than a visible error.