Handy Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require edfa3ly/handy-form-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Edfa3ly\HandyFormBundle\Edfa3lyHandyFormBundle::class => ['all' => true],
   ];
   

2. First Use Case Use a custom form type in a Symfony form builder:

   use Edfa3ly\HandyFormBundle\Form\Type\DatePickerType;
   
   $builder->add('eventDate', DatePickerType::class);
   

   Ensure jQueryUI assets are loaded in your template:

   {{ encore_entry_link_tags('app') }}
   

3. Where to Look First

   • Check Resources/doc/index.md for detailed usage.
   • Review Form/Type/ for available form types.
   • Inspect Resources/public/js/ for JS dependencies.

Implementation Patterns

Common Workflows

1. Basic Integration Replace standard Symfony form types with bundle equivalents:

   // Before
   $builder->add('birthday', DateType::class);
   
   // After
   $builder->add('birthday', DatePickerType::class, [
       'widget_attr' => ['class' => 'datepicker']
   ]);
   

2. Dynamic Form Fields Use CollectionType for dynamic fields (e.g., multi-step forms):

   $builder->add('items', CollectionType::class, [
       'entry_type' => TextType::class,
       'allow_add' => true,
       'allow_delete' => true,
       'prototype' => true,
   ]);
   

3. Dependent Fields Chain Select2DependentFieldType for cascading selects:

   $builder->add('country', CountryType::class);
   $builder->add('state', StateType::class, [
       'dependent_field' => 'country',
   ]);
   

4. Asset Management Load jQueryUI assets via Webpack Encore:

   // webpack.config.js
   Encore
       .addEntry('app', './assets/app.js')
       .copyFiles({
           from: './vendor/edfa3ly/handy-form-bundle/public',
           to: 'bundles/handy-form/[path][name].[ext]'
       });
   

5. TinyMCE Integration Configure TinyMCE in config/packages/edfa3ly_handy_form.yaml:

   edfa3ly_handy_form:
       tinymce:
           api_key: 'your-api-key'
           plugins: ['advlist', 'autolink']
   

Integration Tips

• Doctrine ORM: Use MultiSelectType with ThraceDataGridBundle for grid-based selects.
• Validation: Extend form types to add custom validation:

  use Symfony\Component\Validator\Constraints as Assert;
  
  $builder->add('rating', RatingType::class, [
       'constraints' => [new Assert\NotBlank(), new Assert\Range(['min' => 1, 'max' => 5])],
  ]);
  

• Theming: Override Twig templates in templates/Edfa3lyHandyFormBundle/ to customize rendering.

Gotchas and Tips

Pitfalls

1. Asset Loading

   • Issue: Missing jQueryUI assets cause form types to fail silently.
   • Fix: Ensure jquery-ui is installed and loaded before bundle JS:

     {{ encore_entry_script_tags('app') }}
     <script src="https://code.jquery.com/ui/1.12.1/jquery-ui.min.js"></script>
     

2. PHP Version Compatibility

   • Issue: Bundle may not support PHP 8.x features if not updated.
   • Fix: Check composer.json for php requirement and test locally.

3. TinyMCE API Key

   • Issue: TinyMCE fails with "Invalid API key" errors.
   • Fix: Verify edfa3ly_handy_form.yaml configuration or use a free key from TinyMCE.

4. CollectionType Prototype

   • Issue: Dynamic fields don’t render correctly.
   • Fix: Ensure prototype: true and allow_add: true are set, and check for JS errors in browser console.

5. Recaptcha

   • Issue: Recaptcha not loading due to missing sitekey/secret.
   • Fix: Configure in config/packages/edfa3ly_handy_form.yaml:

     edfa3ly_handy_form:
         recaptcha:
             site_key: 'your-site-key'
             secret: 'your-secret-key'
     

Debugging

• Console Errors: Use Symfony’s profiler (/_profiler) to inspect form rendering issues.
• Network Tab: Check if JS/CSS assets are loaded (404s indicate missing Encore configuration).
• Form Dump: Debug form structure with:

  dump($form->createView());
  

Extension Points

1. Custom Form Types Extend existing types (e.g., DatePickerType) by creating a subclass:

   use Edfa3ly\HandyFormBundle\Form\Type\DatePickerType as BaseDatePicker;
   
   class CustomDatePickerType extends BaseDatePicker {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults(['custom_option' => true]);
       }
   }
   

2. Override Templates Copy Resources/views/Form/ to templates/Edfa3lyHandyFormBundle/Form/ to customize Twig templates.

3. Configuration Extend bundle config in config/packages/edfa3ly_handy_form.yaml:

   edfa3ly_handy_form:
       default_options:
           widget_attr:
               class: 'my-custom-class'
   

4. Event Listeners Subscribe to form events (e.g., PRE_SET_DATA) to modify behavior:

   use Symfony\Component\Form\FormEvent;
   use Symfony\Component\Form\FormEvents;
   
   $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
       $data = $event->getData();
       // Modify form based on $data
   });
   

Pro Tips

• Lazy Loading: Use lazy: true for large collections to improve performance.
• AJAX Dependencies: For Select2DependentFieldType, handle AJAX responses in a custom JS file:

  $(document).on('change', '#country', function() {
      $.get('/api/states/' + $(this).val(), function(states) {
          $('#state').html(states).trigger('change');
      });
  });
  

• Testing: Mock form types in PHPUnit:

  $formFactory = $this->createMock(FormFactoryInterface::class);
  $formFactory->expects($this->once())
      ->method('createNamed')
      ->with('form', DatePickerType::class, $options)
      ->willReturn($form);