Title Widget Laravel Package

Getting Started

This is not a general-purpose library — it is a Victoire CMS widget bundle. It only makes sense inside a Symfony application running Victoire (Symfony 2.8/3.x era). If you are not on Victoire, there is nothing here to use.

Minimal setup:

1. composer require victoire/title-widget — expect the 2017 constraint set (symfony/symfony ^2.8|^3.0, old PHP). You will likely need --ignore-platform-reqs or a Composer platform override on modern PHP.
2. Register the bundle in app/AppKernel.php alongside VictoireCoreBundle / VictoireWidgetBundle.
3. Enable the widget in your Victoire configuration (widgets are opt-in) and clear the cache.
4. Run the Doctrine schema update — the widget is a persisted entity, so the table must exist before editors can drop one in.
5. In the Victoire backend, edit a page, enter a widget zone, and add the "Title" widget.

Where to look first, in this order:

• The widget model/entity (e.g. WidgetTitle.php) — this is the persisted payload and tells you exactly which fields exist (title, body, etc.).
• The form type (Form/WidgetTitleType.php) — this is the editor-facing contract and the file you will most often override.
• Resources/views/.../view.html.twig — the front-end rendering; this is what you will most often restyle.

The first real use case is trivial: letting a content editor insert a heading inside a widget zone without hand-editing templates. The value is editorial, not technical.

Implementation Patterns

Template override (the 90% case). Do not edit the bundle. Override the view from your app: either via bundle inheritance (getParent() in your own bundle) or by placing a file at the same relative path under app/Resources/VictoireWidgetTitleBundle/views/. This is how you add wrappers, anchor IDs, utility classes, or change the tag.

Heading level as a field. The most common extension is a level choice field (h1–h6) rendered directly into the tag: <{{ widget.level|default('h2') }}>. Keep the default sane so existing content does not break when the field is added.

Extending the form type. Subclass the bundle's form type, add your fields (subtitle, eyebrow text, anchor slug), and point the widget at your type. Because Symfony 2/3 service definitions here are explicit YAML/XML with no autowiring, remember to declare the new type as a service and tag/alias it.

Fork-as-a-scaffold. Given the age and the size, the most reliable pattern is to copy the bundle into src/ as your own AppTitleWidgetBundle and adapt it. You get a working reference implementation of the Victoire widget contract (entity + form + template + registration) without inheriting an unmaintained dependency.

Composition with page templates. Use this widget for section headings inside business/page templates where the layout is fixed but the copy is editorial. Keep it out of places where the heading is structural (navigation, hero) — those belong in the template, not in a widget.

Front-end integration. Treat the widget output as semantic HTML only; do styling in your theme's CSS targeting the rendered tag, not by adding classes in the bundle. That keeps overrides cheap when you upgrade.

Gotchas and Tips

• It is effectively unmaintained. Last release June 2017, 2 stars, zero dependents. Pin the exact version, commit your composer.lock, and budget for vendoring or forking. Do not build a critical editorial path on it without a maintenance plan.
• Platform requirements will bite first. Old Symfony/PHP constraints mean Composer resolution fails on modern stacks before you write a line of code. Decide up front whether you are overriding the platform config or forking.
• The widget is persisted. Fields live in the database. Adding a field to the form type without a schema migration yields silent nulls, not errors. Always run the migration before testing in the UI.
• Cache is the usual culprit. Victoire caches widget rendering and template resolution aggressively. After any template override, cache:clear and check the environment — "my override isn't applied" is almost always a stale cache or a wrong override path.
• Heading hierarchy / SEO. Multiple title widgets in one page can easily produce several h1s. Enforce the level field's default and document the editorial rule; this is the single most common content-quality bug with heading widgets.
• Registration mismatch. If the widget does not appear in the picker, verify the widget name used in Victoire config matches the one registered by the bundle exactly — case and namespace — and that the bundle is actually enabled for that business template.
• Debugging path. debug:container to confirm the widget and form type services are registered, then inspect the Victoire widget registry config, then the rendered slot markup. Work outward from the service container; guessing at templates wastes time.
• Translation and defaults. Placeholder/empty-state text is easy to leave hardcoded. Route it through the translator so multilingual Victoire installs do not leak English into the editor UI.
• Extension point to prefer. The form type and the Twig template are the two supported seams. Anything deeper (changing the entity, altering persistence) means you should fork rather than patch, because there is no upstream to send fixes to.