Form Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require genemu/form-bundle "^4.0"
   

   Add to AppKernel.php:

   new Genemu\Bundle\FormBundle\GenemuFormBundle(),
   

2. Initialize Assets:

   php app/console assets:install web/
   

3. First Use Case: Use Select2 for enhanced dropdowns in a form:

   use Genemu\Bundle\FormBundle\Form\Type\Select2Type;
   
   $builder->add('user', Select2Type::class, [
       'choices' => ['user1' => 'User 1', 'user2' => 'User 2'],
       'multiple' => true,
       'ajax' => true, // Enable AJAX if needed
   ]);
   

   Key Files to Review:

   • Resources/doc/jquery/select2/index.md (Select2 docs)
   • Resources/doc/recaptcha/index.md (ReCaptcha setup)

Implementation Patterns

Common Workflows

1. Select2 Integration:

   • Use for searchable, taggable dropdowns.
   • Configure AJAX endpoints for dynamic data loading:

     $builder->add('tags', Select2Type::class, [
         'ajax' => [
             'url' => '/api/tags',
             'data' => ['param' => 'value'],
         ],
     ]);
     

2. Captcha Integration:

   • GD Captcha (basic):

     $builder->add('captcha', 'genemu_form_captcha_gd');
     

   • ReCaptcha (Google):

     $builder->add('recaptcha', 'genemu_form_recaptcha', [
         'public_key' => 'YOUR_PUBLIC_KEY',
         'private_key' => 'YOUR_PRIVATE_KEY',
     ]);
     

3. jQuery UI Components:

   • Autocomplete:

     $builder->add('search', 'genemu_form_jqueryui_autocomplete', [
         'source' => '/api/search',
     ]);
     

Integration Tips

• Asset Management: Ensure assets:install is run post-install. Manually include JS/CSS in templates if needed:

  {{ asset('bundles/genemuform/js/select2.min.js') }}
  

• Validation: Validate ReCaptcha responses in form handlers:

  $response = $form->get('recaptcha')->getData();
  $recaptcha = new \Genemu\Bundle\FormBundle\Validator\Constraints\ReCaptcha();
  $validator = $this->get('validator');
  $errors = $validator->validate($response, [$recaptcha]);
  

• Dynamic Forms: Use pre_set_data for AJAX-loaded Select2 options:

  $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
      $form = $event->getForm();
      $data = $event->getData();
      $form->add('dynamic_field', Select2Type::class, [
          'choices' => $this->getDynamicChoices($data),
      ]);
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • No active maintenance; expect compatibility issues with newer Symfony/Laravel versions.
   • Workaround: Fork the repo and update dependencies manually (e.g., Symfony 4/5 compatibility).

2. Asset Paths:

   • Hardcoded asset paths may break post-upgrade. Override templates or use asset() helper.

3. ReCaptcha v2+:

   • Original bundle uses ReCaptcha v1. Update to v2/3 manually if needed:

     // Override type class in config/services.yaml
     Genemu\Bundle\FormBundle\Form\Type\ReCaptchaType: ~
     

4. GD Captcha Fonts:

   • Requires GD library (php-gd). Install via:

     sudo apt-get install php-gd  # Debian/Ubuntu
     

Debugging

• Select2 AJAX Failures: Check browser console for 404s on AJAX endpoints. Verify:

  • Route exists (php app/console router:debug).
  • CORS headers if using cross-domain requests.

• ReCaptcha Errors: Validate keys and enable debug mode:

  $builder->add('recaptcha', 'genemu_form_recaptcha', [
      'debug' => true, // Logs errors to console
  ]);
  

Extension Points

1. Custom Form Types: Extend existing types (e.g., Select2Type) for reusable components:

   namespace App\Form\Type;
   
   use Genemu\Bundle\FormBundle\Form\Type\Select2Type;
   
   class CustomSelect2Type extends Select2Type {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_option' => true,
           ]);
       }
   }
   

2. Override Templates: Copy bundle templates (e.g., Resources/views/Form/fields.html.twig) to app/Resources/GenemuFormBundle/views/Form/ to customize rendering.

3. Event Listeners: Hook into form events for dynamic behavior:

   // src/EventListener/FormListener.php
   public function onFormPreSetData(FormEvent $event) {
       $form = $event->getForm();
       $form->add('field', Select2Type::class, ['choices' => [...]]);
   }
   

   Register in services.yaml:

   services:
       App\EventListener\FormListener:
           tags: [kernel.event_listener, { event: form.pre_set_data, method: onFormPreSetData }]