Form Widget Laravel Package

Getting Started

• Install into an existing Victoire/Symfony project with composer require victoire/form-widget. This is a legacy-era bundle — check its composer.json constraints before assuming compatibility with modern Symfony.
• Register the bundle in AppKernel (or bundles.php if backported). Confirm the exact bundle class from vendor/victoire/form-widget/ — likely Victoire\Widget\FormBundle\VictoireWidgetFormBundle.
• Run any shipped migrations, then clear cache. Look first at:
  • Resources/config/ for services, routing, and widget registration
  • Widget/ for the form widget entity/class
  • Form/ for bundled form types
  • Resources/views/ for the front-end Twig template
• First use case: add the form widget to a Victoire page, configure its fields or select a form type, render the page, submit the form, and verify where submissions go (email, persistence, or a controller response).
• Because the package has very low adoption and a 2018 release, treat the source as the documentation. Confirm whether the bundle stores submissions, only renders forms, or expects you to provide submit handling.

Implementation Patterns

• Use the bundle as glue between Victoire’s widget editor and Symfony Form. Define a Symfony form type for the fields you need, then expose/select that type through the widget configuration.
• Render forms in an overridden widget template using standard Twig form helpers:
  • form_start(form, { action: path(...) })
  • form_row / form_widget / form_errors
  • form_end(form)
• Handle submission explicitly. Locate the bundle’s submit route/controller; if it only renders, add your own controller action that:
  1. Creates and handles the form
  2. Validates
  3. Persists a submission entity or sends email
  4. Redirects after success to avoid duplicate POSTs
• For custom fields, create a form type and matching Twig block/theme override. Map widget settings to form options with data transformers where needed.
• For persistence, create a FormSubmission entity related to the widget/page and store serialized field values plus metadata (IP, user agent, created date). Keep PII retention rules in mind.
• Integrate with existing services: Symfony Mailer/SwiftMailer, Doctrine entity manager, event dispatcher. Use a post-submit event or subscriber so multiple widgets can share notification logic.
• Add spam controls at the form-type level: honeypot field, time trap, captcha, rate limiting. Do not rely on the widget package for this.
• When extending, prefer a custom widget class or template override over editing vendor code. Register custom form types as services and reference them from widget configuration.

Gotchas and Tips

• Maintenance risk is high: last release 2018, 4 stars, no dependents. Pin the package version, expect to fork, and avoid relying on upstream fixes.
• Compatibility is the biggest trap. The bundle likely targets Symfony 2.8/3.x-era APIs (AppKernel, YAML service config, old templating). Test install in a branch before committing.
• Form action and routing can break behind proxies, localized routes, or subdirectory installs. Always inspect the rendered <form action> and test POST directly.
• Victoire page caching can cache CSRF tokens or stale form markup. Ensure form-containing pages/widgets are excluded from full-page cache or rendered dynamically.
• Multiple form widgets on one page can collide on form names. Set unique form names per widget instance.
• File uploads need enctype="multipart/form-data", an upload directory, and validation. Check whether the bundle’s template includes the enctype; override if not.
• Collection/repeated/choice fields often need custom JavaScript and template blocks. Test add/remove behavior and validation errors carefully.
• Debugging checklist:
  • Confirm the widget appears in Victoire’s widget picker.
  • Check container compilation and service tags.
  • Use debug:router to find submit routes.
  • Use the Symfony profiler to inspect form errors, CSRF failures, and request data.
  • Clear cache after template/service/config changes.
• Extension points to prefer: widget template overrides, custom form types, event subscribers, and a custom submit controller. If you need modern Symfony support, plan a fork rather than a light integration.