Form Bundle Laravel Package

Getting Started

enhavo/form-bundle is not a standalone form library — it is a read-only subtree split of the main enhavo/enhavo CMS. That means:

• Do not clone or patch this repository directly. Any change must go through the main repository and will be re-split downstream.
• In a real project you almost never require enhavo/form-bundle in isolation. You require enhavo/enhavo (or the relevant Enhavo meta-package) and let it pull the form bundle in. Installing the split alone is only reasonable if you already have the Enhavo core/resource/admin bundles wired up.
• There is effectively no documentation in this repo. The README is a pointer to the main project, so your first stop is the main repository's docs, src/Resources/config/, and the bundle's own PHP source.

Minimal path to first use:

1. composer require enhavo/enhavo (or the specific Enhavo packages you need) in a Symfony application.
2. Register the bundle in config/bundles.php:

   Enhavo\Bundle\FormBundle\EnhavoFormBundle::class => ['all' => true],
   

3. Import the bundle routing if you plan to use its controllers:

   # config/routes/enhavo_form.yaml
   enhavo_form:
       resource: '@EnhavoFormBundle/Resources/config/routing.yaml'
   

4. Ensure Doctrine sees the bundle's entities (Enhavo's resource bundle normally handles mapping configuration — verify Resources/config/doctrine/ exists and is loaded).
5. Run bin/console doctrine:schema:update --dump-sql (or generate a migration) before touching anything at runtime.
6. Clear cache: bin/console cache:clear.

Where to look first, in order:

• src/EnhavoFormBundle.php — bundle registration and any compiler passes.
• src/Resources/config/ — service definitions, form type registrations, routing. This is the de-facto API surface.
• src/Form/Type/ and any FormType/FormField classes — the core abstraction for renderable forms.
• src/Entity/ (or Model/) — the persisted form/submission model.
• src/Resources/views/ — Twig templates you will override.

First realistic use case: define a form (fields, labels, validation) through Enhavo's admin/resource layer, persist it, render it on a frontend route, and handle submissions through the bundle's controller or your own. If you only need generic Symfony forms, do not use this bundle — plain symfony/form is simpler and has actual documentation.

Implementation Patterns

Because the bundle is part of a CMS rather than a form framework, patterns revolve around Enhavo's resource and block abstractions.

Defining a form as a resource. Forms are typically modeled as Doctrine-backed resources managed through the Enhavo admin. The usual pattern is:

• Create/extend the form entity (or use the bundle's base class) with a collection of field definitions.
• Register the entity with Enhavo's resource configuration so it appears in the admin and gets generic CRUD.
• Add a form type in src/Form/Type/ referencing the entity, and wire it in Resources/config/.
• Configure validation via standard Symfony constraints on the entity or through validation.yaml in Resources/config/.

Rendering a form. In a controller or block, load the form entity and hand it to a Symfony FormInterface built from the bundle's form type, then render through the bundle's Twig templates. If the bundle exposes a renderer service (check Resources/config/services.yaml for something like a FormRenderer or FormManager), prefer it over constructing forms manually — it will apply the CMS's field-type conventions consistently.

Extending field types. The clean extension point is Symfony's own form type extension mechanism:

class MyFieldTypeExtension extends AbstractTypeExtension
{
    public static function getExtendedTypes(): iterable
    {
        return [SomeEnhavoFieldType::class];
    }

    public function buildView(FormView $view, FormInterface $form, array $options): void
    {
        $view->vars['my_attribute'] = $options['my_attribute'];
    }
}

Register it with the form.type_extension tag and it will apply to every instance of that field type across the CMS, without forking the bundle.

Overriding templates. Use standard Symfony bundle override resolution: place templates under templates/bundles/EnhavoFormBundle/... mirroring the bundle's Resources/views structure. This is the safest customization path and survives composer updates. For per-form variation, prefer Twig blocks and a theme (form_theme) over copying the whole template.

Integrating with blocks. If your site uses Enhavo's block system, a form is often embedded as a block. The pattern is: a block type referencing a form entity, a template that calls the renderer, and a submission controller that redirects or re-renders with flash messages. Keep submission logic in your application service, not in the bundle's controller, so you can add spam protection, rate limiting, and custom persistence.

Handling submissions. The bundle likely provides a controller for POST handling. Decorating that service (Symfony service decoration) is a cleaner extension point than editing it:

services:
    app.form_controller:
        decorates: 'enhavo_form.controller.form' # verify actual service id
        arguments: ['@app.form_controller.inner']

Use this to add CSRF hardening, honeypots, logging, or to route submissions into your own persistence layer.

Testing. Given the near-zero documentation and dependents, treat the bundle's own test suite (if present under src/Tests/ or tests/) as executable documentation. Write an integration test that boots the kernel, loads a form entity fixture, renders the form, and asserts on field names and validation behavior.

Gotchas and Tips

• Subtree split means you cannot contribute here. PRs against this repository are pointless. Always check whether the issue/feature belongs in the main enhavo/enhavo repo.
• Version alignment is critical. Because this is split automatically, enhavo/form-bundle versions track the monorepo. Mixing versions across Enhavo packages is a common source of "class not found" and service-definition errors. Pin all enhavo/* packages to the same minor version in composer.json.
• Bundle ordering matters. Enhavo bundles assume core/resource/admin bundles are registered. If routes or services are missing, verify bundle order in config/bundles.php — EnhavoFormBundle should load after the core Enhavo bundles.
• Doctrine mappings are easy to miss. Symfony does not auto-discover entity mappings from arbitrary bundles unless they are configured. If you get "The class ... was not found in the chain configured namespaces," check doctrine.orm.mappings and Enhavo's mapping configuration.
• Schema drift. Since migrations are managed in the main repo, running the bundle's own migrations in your app may not be appropriate. Generate your own migrations for the tables you actually use.
• Cache is aggressive. After changing service config, form types, or templates, run cache:clear. In dev, also check var/cache/dev/Container*/ to confirm your service tags registered.
• Zero dependents and zero stars is a signal. There is very little community material, no Stack Overflow corpus, and no third-party tutorials. Budget time for reading source. Consider whether plain symfony/form plus your own persistence covers the requirement — for most non-CMS projects it does, with far less coupling.
• Debugging forms. Use the Symfony profiler's Form panel to inspect submitted data, transformation failures, and validation. For bundle-specific rendering issues, use {{ dump(form.vars) }} and bin/console debug:container --tag=form.type to confirm which types are registered.
• Extension points, ranked by safety: (1) form type extensions and form_theme overrides, (2) service decoration, (3) event subscribers on form events (FormEvents::PRE_SUBMIT, POST_SUBMIT), (4) subclassing bundle classes, (5) editing vendor code — never.
• Watch for BC breaks on upgrade. A CMS monorepo split with sparse docs and no semver guarantees in practice means you should diff Resources/config/services.yaml between versions before upgrading, and run your form integration tests as a gate.