Form Widget Laravel Package

Getting Started

Framework reality check first. friendsofvictoire/form-widget is a Symfony bundle (WidgetFormBundle) built for Victoire, a visual page-builder CMS on Symfony. It is not a Laravel package: there is no service provider, no config publish tag, no Blade views, and no Eloquent anything. A Laravel developer should treat this as either (a) something to use only if you are actually running Symfony + Victoire, or (b) a reference implementation for building a "form widget" concept in your own Laravel page/block system. With 0 stars and 0 dependents, assume it is unmaintained and audit the composer constraints before touching it.

Minimal steps (Symfony/Victoire host app):

1. composer require friendsofvictoire/form-widget — expect resolution pain; check its symfony/*, doctrine/*, and PHP requirements against your app before committing.
2. Register the bundle: AppKernel::registerBundles() on Symfony 2/3-era apps, or config/bundles.php on newer ones. Victoire itself must already be installed and booting.
3. Update the schema for whatever submission/field entities the bundle ships (doctrine:schema:update --force or generate a migration — prefer the migration).
4. bin/console cache:clear and bin/console assets:install --symlink (Symfony 3 style) so widget assets are reachable.
5. Open a page in the Victoire editor, add the Form widget to a slot, configure the fields, save, and render the page.

Where to look first in the repo:

• Widget/ (or Entity/) — the widget entity extending Victoire's base Widget; this is where per-widget configuration lives.
• Form/ — the Symfony Form type(s) that turn widget configuration into rendered fields and handle submission.
• Resources/views/ — Twig templates for the widget itself and the form theme.
• Resources/config/ (or DependencyInjection/) — service wiring, widget registration, and any tagged services Victoire discovers.

First real use case: a contact/quote form that an editor drops onto a marketing page without a deploy. Success = editor configures fields in the page builder, visitor submits, submission is persisted and/or emailed, and the widget renders consistently inside Victoire's slot layout.

Implementation Patterns

Understand the widget contract before writing code. Victoire widgets are Doctrine entities extending a base widget class, paired with a Symfony Form type that edits the widget's own settings, and a Twig template that renders it in a slot. Two shapes are common:

• One widget type per form — e.g. ContactWidget, QuoteWidget. Explicit, easy to template, but every new form is a class + entity + template + migration.
• One generic form widget with a configurable field schema — field definitions stored as JSON/array on the widget, dynamically expanded into a Symfony Form at render time. More flexible, but you own validation, sanitization, and the editor UI for field definitions.

For day-to-day work, the second pattern scales better; the first is safer if the bundle only gives you a thin base.

Rendering pattern. Keep the widget template thin: it should output a wrapper, the form open/close, CSRF token, and delegate field rendering to a form theme. Override the bundle template rather than editing vendor code — in modern Symfony, add a twig.paths entry pointing at templates/bundles/WidgetFormBundle/; on legacy apps use app/Resources/WidgetFormBundle/views/.

Submission handling. Treat submission as a normal Symfony form POST:

• A controller or a dedicated submission service validates the form.
• Persist to a submission entity (one row per submit, with the widget/page reference so editors can see which page produced it).
• Dispatch an event or call a mailer service; do not hardcode Swift_Mailer/\Swift_Message calls in the widget — Symfony 4+ apps will need MailerInterface/Email.
• Add a honeypot or rate limiter; these widgets are public-facing by definition.

Integration tips.

• Store the widget/page context on the submission (widget_id, page slug, locale) so exports and spam triage are possible later.
• Use a translation domain for field labels and validation messages instead of hardcoding strings in templates.
• If editors need to pick recipients or success messages, put those on the widget entity, not in Twig.
• Wire submission storage into an admin list (Sonata/EasyAdmin or a custom controller) — otherwise the data is write-only.
• If you are a Laravel dev porting the concept: the widget ≈ a Blade/Livewire component or a Filament block; the Symfony Form type ≈ FormRequest + validation rules; Doctrine entities ≈ Eloquent models; Victoire's slot rendering ≈ your block renderer. Port the shape, not the code.

Extension points worth knowing: form type extensions for shared field behavior, event subscribers for post-submit hooks, custom widget templates, and service decoration of the bundle's submission/notification service if one exists. Prefer decoration over forking.

Gotchas and Tips

• Composer will fight you. A bundle targeting Victoire (Symfony 2.8/3.x era) will typically pin old symfony/form, symfony/http-foundation, and Doctrine versions that conflict with Laravel 9–11's illuminate/* constraints. You cannot meaningfully install this in a Laravel app; require it only in a Symfony project, and expect to relax or fork constraints.
• Zero stars, zero dependents. No community support, no security advisories, no guaranteed PHP 8 compatibility. Pin the exact commit in composer.json and budget for owning the code.
• Doctrine schema ownership. The bundle's entities live in your app's schema. Always generate a migration rather than running schema:update in production, and check for table-name collisions.
• Cache is aggressive. Victoire caches rendered widgets and page structures. After editing templates or widget config, clear the cache — otherwise you will debug a "broken template" that is actually a stale cache entry.
• Form rendering quirks. If fields render unstyled or without errors, you are missing the form theme or the widget template is calling form_widget without form_start/form_end. Check form_errors(form) and per-field errors explicitly.
• CSRF and session scope. Widgets embedded on cached pages can break CSRF tokens. If pages are HTTP-cached, either exclude the form route from caching or use a stateless token strategy.
• File uploads need their own handling (mime validation, storage path, cleanup) — do not assume the bundle does it.
• GDPR/data retention. Submissions contain personal data. Plan retention, export, and deletion from day one; a plain submissions table with no admin tooling becomes a liability.
• Debugging toolkit: Symfony profiler's Forms panel (shows submitted data and validation), debug:container --tag=victoire.widget (or the equivalent tag) to confirm registration, debug:router for the submit endpoint, and Twig's dump() in dev.
• Upgrade path: before investing, diff the bundle against Victoire's current widget API. If Victoire has moved to newer Symfony, this bundle's base classes likely will not load, and you are better off writing a small in-house widget following the patterns above.