Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require drosalys-web/form-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Drosalys\Web\FormBundle\FormBundle::class => ['all' => true],
   ];
   

2. Basic Form Usage Extend Symfony’s AbstractType to leverage the bundle’s features:

   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   use Drosalys\Web\FormBundle\Form\Type\ExtendedFormType;
   
   class MyFormType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder
               ->add('field_name', ExtendedFormType::class, [
                   'attr' => ['class' => 'custom-class'],
                   'label' => 'Custom Label',
                   'required' => true,
               ]);
       }
   }
   

3. First Use Case: Dynamic Field Attributes Use the bundle’s ExtendedFormType to inject dynamic attributes (e.g., data-* or class):

   {{ form_start(form) }}
       {{ form_widget(form.field_name) }} {# Renders with injected attributes #}
   {{ form_end(form) }}
   

Implementation Patterns

1. Field Customization & Reusability

• Dynamic Attributes: Extend base fields with custom attributes via ExtendedFormType:

  $builder->add('email', ExtendedFormType::class, [
      'attr' => ['data-validation' => 'email'],
  ]);
  

• Field Templates: Override Twig templates in templates/form/ (e.g., form_div_layout.html.twig) to modify rendering.

2. Validation & Error Handling

• Custom Validators: Integrate with Symfony’s validator system:

  use Drosalys\Web\FormBundle\Validator\Constraints\CustomConstraint;
  
  $builder->add('username', TextType::class, [
      'constraints' => [new CustomConstraint()],
  ]);
  

• Error Rendering: Use the bundle’s form_errors Twig function for consistent error display:

  {% form_errors form.field_name %}
  

3. Form Events & Subscribers

• Event Listeners: Attach listeners to modify form behavior:

  use Drosalys\Web\FormBundle\Event\FormEvents;
  
  $eventDispatcher->addListener(FormEvents::PRE_SUBMIT, function ($event) {
      $data = $event->getData();
      // Modify data before submission
  });
  

• Form Subscribers: Create subscribers for cross-cutting concerns (e.g., logging):

  use Drosalys\Web\FormBundle\Event\FormEvents;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class FormLoggerSubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents()
      {
          return [FormEvents::POST_SUBMIT => 'logSubmission'];
      }
  }
  

4. Integration with Laravel (Symfony Bridge)

• Laravel Forms: Use the bundle via Symfony’s Form component (if using Laravel’s Symfony bridge):

  use Symfony\Component\Form\FormFactoryInterface;
  
  $formFactory = app(FormFactoryInterface::class);
  $form = $formFactory->create(MyFormType::class);
  

• Laravel Validation: Map Symfony constraints to Laravel’s validation rules (e.g., NotBlank → required).

Gotchas and Tips

Pitfalls

1. Template Overrides

   • Overriding Twig templates requires naming them exactly (e.g., form_div_layout.html.twig). Misnaming breaks rendering.
   • Fix: Verify template paths in config/packages/drosalys_web_form.yaml.

2. Event Dispatcher Conflicts

   • If using Laravel’s event system, ensure Symfony’s EventDispatcher is not overridden.
   • Fix: Use Laravel’s Event facade for Laravel-specific events and Symfony’s for form events.

3. Constraint Validation

   • Custom constraints must implement Constraint interface. Forgetting this causes silent failures.
   • Fix: Extend AbstractConstraint for validation logic.

Debugging Tips

• Form Dumping: Use Symfony’s Form dumper for debugging:

  $form->dump();
  

• Twig Debug: Enable Twig’s debug mode to inspect rendered fields:

  {% if app.debug %}{% form_theme form _self %}{% endif %}
  

Extension Points

1. Custom Field Types Extend ExtendedFormType to create reusable field types:

   class CustomSelectType extends ExtendedFormType
   {
       public function configureOptions(OptionsResolver $resolver)
       {
           $resolver->setDefaults(['choices' => []]);
       }
   }
   

2. Form Themes Create a custom theme directory (templates/form/) and reference it in Twig:

   {% form_theme form ['form_theme.html.twig'] %}
   

3. Configuration Override bundle settings in config/packages/drosalys_web_form.yaml:

   drosalys_web_form:
       default_attr: { class: 'form-control' }
   

Performance

• Caching: Enable Symfony’s form caching for repeated forms:

   # config/packages/framework.yaml
   form:
       enabled: true
       cache: true