Form Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Add the bundle to composer.json:

   composer require devmachine/form-bundle:~2.0
   

   Register the bundle in config/bundles.php:

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

2. Enable Form Types Import the bundle’s routing (if needed) and ensure DevmachineFormBundle is loaded in config/packages/devmachine_form.yaml (if provided). Check for default configuration in config/packages/devmachine_form.yaml (create if missing).

3. First Use Case: Bootstrap Date Widget Create a form type extending Devmachine\Form\Type\DateType:

   use Devmachine\Form\Type\DateType;
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class MyDateType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('eventDate', DateType::class, [
               'widget' => 'single_text', // or 'split', 'bootstrap_datepicker'
               'format' => 'yyyy-MM-dd',
           ]);
       }
   }
   

Implementation Patterns

Common Workflows

1. Bootstrap Date/Datetime Widgets

   • Use DateType/DateTimeType with widget options:

     $builder->add('birthday', DateType::class, [
         'widget' => 'bootstrap_datepicker',
         'format' => 'dd/MM/yyyy',
         'html5' => false, // Disable HTML5 validation
     ]);
     

   • Integration Tip: Ensure bootstrap-datepicker JS/CSS is included in your base template.

2. Typeahead Autocomplete

   • Configure TypeaheadType with a data source (e.g., API endpoint):

     $builder->add('user', TypeaheadType::class, [
         'min_length' => 2,
         'source' => '/api/users/autocomplete',
         'display_field' => 'fullName',
         'value_field' => 'id',
     ]);
     

   • Workflow: Use data-src attribute in Twig:

     {{ form_widget(form.user, {'attr': {'data-src': path('app_user_autocomplete')}}) }}
     

3. Dynamic Forms

   • Combine with Symfony’s form_row and form_errors in Twig:

     {% for field in form %}
         <div class="form-group">
             {{ form_label(field) }}
             {{ form_widget(field) }}
             {% if form_errors(field) %}
                 <div class="text-danger">{{ form_errors(field) }}</div>
             {% endif %}
         </div>
     {% endfor %}
     

4. Custom Validation

   • Extend form types to add validation:

     use Symfony\Component\Validator\Constraints as Assert;
     
     $builder->add('email', TextType::class, [
         'constraints' => [
             new Assert\Email(),
             new Assert\NotBlank(),
         ],
     ]);
     

Integration Tips

• Asset Management: Bundle requires bootstrap-datepicker and typeahead.js. Add to webpack.config.js or include via <script> tags.
• Twig Extensions: Use form_row with custom classes:

  {{ form_row(form.field, {'attr': {'class': 'form-control'}}) }}
  

• API-Driven Autocomplete: For TypeaheadType, ensure the endpoint returns JSON:

  [{"id": 1, "fullName": "John Doe"}, ...]
  

Gotchas and Tips

Pitfalls

1. Missing JavaScript Dependencies

   • Error: Autocomplete/datepicker fails silently.
   • Fix: Verify bootstrap-datepicker and typeahead.js are loaded after jQuery.
   • Debug: Check browser console for 404 errors on /bundles/devmachineform/....

2. HTML5 Validation Conflicts

   • Issue: html5: true may override custom formats.
   • Fix: Set html5: false for full control:

     'widget' => 'bootstrap_datepicker',
     'html5' => false,
     

3. Caching Static Assets

   • Problem: Bundle assets may not update if cached.
   • Solution: Clear cache or append query strings:

     <script src="{{ asset('bundles/devmachineform/js/typeahead.bundle.js?v=2') }}"></script>
     

4. Deprecated Symfony Features

   • Note: Bundle targets Symfony 3.x. For Symfony 5/6, expect compatibility issues (e.g., FormBuilder changes).

Debugging

• Form Rendering Issues: Use {{ dump(form.vars) }} to inspect form variables.
• Autocomplete Not Working: Verify:
  • Endpoint returns valid JSON.
  • data-src attribute matches the route.
  • No CORS errors (if using external APIs).

Extension Points

1. Custom Widgets Extend Devmachine\Form\Type\AbstractWidgetType to create new widgets:

   class CustomWidgetType extends AbstractWidgetType
   {
       protected function configureOptions(OptionsResolver $resolver)
       {
           $resolver->setDefaults([
               'widget' => 'custom_widget',
           ]);
       }
   }
   

2. Override Default Templates Copy templates from vendor/devmachine/form-bundle/Resources/views/Form/ to templates/Form/ to customize rendering.

3. Configuration Overrides Override defaults in config/packages/devmachine_form.yaml:

   devmachine_form:
       date:
           default_widget: 'bootstrap_datepicker'
           format: 'dd/MM/yyyy'
   

Pro Tips

• Leverage Symfony’s Form Events Use PRE_SET_DATA/POST_SUBMIT to dynamically adjust form fields:

  $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
      $data = $event->getData();
      if ($data->isAdmin()) {
          $event->getForm()->add('adminOptions', CheckboxType::class);
      }
  });
  

• Combine with Laravel Mix Bundle assets with mix.js('resources/js/app.js', 'public/js') and include them in your layout:

  {{ mix('js/app.js') }}