Form Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation:

   composer require genemu/form-bundle
   

   Ensure compatibility with your Symfony version (e.g., 2.1.* for Symfony 2.1/2.2).

2. Enable the Bundle: Add to app/AppKernel.php:

   new Genemu\Bundle\FormBundle\GenemuFormBundle(),
   

3. Initialize Assets:

   php app/console assets:install web/
   

4. First Use Case: Use Select2 for an enhanced dropdown in a form:

   // src/AppBundle/Form/Type/MyType.php
   use Genemu\Bundle\FormBundle\Form\Type\Select2Type;
   
   $builder->add('fieldName', Select2Type::class, [
       'choices' => ['Option 1', 'Option 2'],
       'placeholder' => 'Select an option',
   ]);
   

   Ensure JavaScript/CSS assets are loaded in your template:

   {{ form_widget(form) }}
   {% block javascripts %}
       {{ parent() }}
       {{ asset('bundles/genemuform/js/select2.min.js') }}
       {{ asset('bundles/genemuform/css/select2.css') }}
   {% endblock %}
   

Implementation Patterns

Common Workflows

1. Select2 Integration:

   • Use for searchable, taggable dropdowns (e.g., user roles, categories).
   • Configure via options:

     $builder->add('tags', Select2Type::class, [
         'multiple' => true,
         'ajax' => [
             'url' => '/api/tags',
             'data' => ['id' => 'query'],
         ],
     ]);
     

   • Twig: Render with {{ form_widget(form.tags) }} and include Select2 JS/CSS.

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',
     ]);
     

   • Validate via event subscriber or custom validator.

3. TinyMCE Editor:

   • Embed a WYSIWYG editor:

     $builder->add('content', 'genemu_form_tinymce', [
         'config' => [
             'plugins' => 'link image',
             'toolbar' => 'bold italic | link image',
         ],
     ]);
     

   • Load TinyMCE assets in Twig:

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

Integration Tips

• Asset Management: Use assets:install for production and assets:debug for development. Override asset paths in config.yml if needed:

  genemu_form:
      assets_path: '%kernel.root_dir%/../vendor/genemu/form-bundle/web'
  

• Dynamic Forms: Combine with Symfony’s FormEvent to conditionally add fields (e.g., show ReCaptcha only on registration).

• Validation: Extend default validators (e.g., for ReCaptcha):

  use Genemu\Bundle\FormBundle\Validator\Constraints\ReCaptcha;
  
  $builder->add('recaptcha', null, [
      'constraints' => [new ReCaptcha()],
  ]);
  

Gotchas and Tips

Pitfalls

1. Asset Loading:

   • Forgetting to run assets:install or missing JS/CSS in templates causes silent failures.
   • Fix: Verify assets are copied to web/bundles/genemuform/ and included in Twig.

2. Select2 AJAX Dependencies:

   • If using AJAX, ensure the endpoint returns valid JSON:

     [{ "id": 1, "text": "Option 1" }, ...]
     

   • Debug: Check browser’s Network tab for failed AJAX requests.

3. TinyMCE Configuration:

   • Custom configs may conflict with default settings. Test in isolation:

     'config' => json_decode(file_get_contents('path/to/custom_config.json'), true),
     

4. ReCaptcha Errors:

   • Invalid keys or network issues may return empty responses.
   • Debug: Log the response from Google’s API to verify keys and quota limits.

5. Symfony Version Mismatch:

   • Using 2.1.* with Symfony 2.3+ may break due to deprecated APIs.
   • Fix: Pin to the correct version in composer.json.

Debugging Tips

• Form Rendering: Use {{ dump(form.vars) }} in Twig to inspect form variables and options.

• JavaScript Errors: Check the browser console for missing dependencies (e.g., jQuery for Select2/TinyMCE). Fix: Ensure jQuery is loaded before bundle assets.

• Captcha Validation: For GD Captcha, verify the captcha session key matches the submitted value:

  $session->get('captcha', null) === $submittedValue
  

Extension Points

1. Custom Form Types: Extend existing types (e.g., Select2Type) by overriding the buildView/buildForm methods:

   class CustomSelect2Type extends Select2Type {
       public function buildView(FormView $view, FormInterface $form, array $options) {
           $view->vars['custom_option'] = 'value';
       }
   }
   

2. Asset Overrides: Override bundle assets by copying files to web/bundles/genemuform/ and modifying them.

3. Event Subscribers: Listen to form events to dynamically alter fields:

   // src/AppBundle/EventListener/FormListener.php
   public function onPreSetData(FormEvent $event) {
       $form = $event->getForm();
       if ($event->getData()->isAdmin()) {
           $form->add('admin_field', Select2Type::class);
       }
   }