Symfony Tailwind Form Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ecohead/symfony-tailwind-form-theme-bundle
   

   For non-Flex projects, manually register the bundle in config/bundles.php:

   Ecohead\TailwindFormTheme\EcoheadTailwindFormThemeBundle::class => ['all' => true],
   

2. Enable Tailwind Theme: Add the theme to your form types in config/packages/twig.yaml:

   twig:
       form_themes: ['@EcoheadTailwindFormTheme/form/theme.html.twig']
   

3. First Use Case: Use the bundle in a form type:

   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class MyFormType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->add('name', TextType::class, [
               'attr' => ['class' => 'w-full p-2 border rounded'],
           ]);
       }
   }
   

   Render the form in Twig:

   {{ form_start(form) }}
       {{ form_widget(form) }}
   {{ form_end(form) }}
   

Implementation Patterns

Workflows

1. Form Customization: Override the default theme by extending the base template (theme.html.twig) in your project’s templates/form/ directory. Example: Copy @EcoheadTailwindFormTheme/form/theme.html.twig to templates/form/tailwind_theme.html.twig and customize.

2. Dynamic Class Assignment: Use the attr option to add Tailwind classes to form fields:

   $builder->add('email', EmailType::class, [
       'attr' => ['class' => 'mt-4 p-3 border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500'],
   ]);
   

3. Integration with Symfony UX: Combine with Symfony UX Turbo for dynamic form updates:

   {{ form_start(form, {'attr': {'data-turbo-frame': '_self'}}) }}
       {{ form_widget(form) }}
   {{ form_end(form) }}
   

4. Reusable Form Blocks: Create modular form components in Twig:

   {# templates/components/input.html.twig #}
   <div class="mb-4">
       {{ form_label(form) }}
       {{ form_widget(form) }}
       {{ form_errors(form) }}
   </div>
   

Integration Tips

• Tailwind Config: Ensure your tailwind.config.js includes form-related classes (e.g., focus:ring-*, border-*).
• Symfony Form Events: Use PRE_SET_DATA or POST_SUBMIT to dynamically adjust form attributes:

  $builder->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
      $event->getForm()->add('dynamic_field', TextType::class, [
          'attr' => ['class' => 'bg-red-100'],
      ]);
  });
  

Gotchas and Tips

Pitfalls

1. Theme Override Conflicts:

   • If customizing the theme, ensure your template extends the base theme correctly:

     {# templates/form/tailwind_theme.html.twig #}
     {% extends '@EcoheadTailwindFormTheme/form/theme.html.twig' %}
     

   • Avoid duplicating blocks like form_row or form_widget without extending them.

2. Tailwind Class Mismatches:

   • Verify Tailwind classes exist in your build (e.g., focus:ring-blue-500 requires @focus-ring-color in tailwind.config.js).
   • Debug missing styles with browser dev tools to check if classes are applied but overridden.

3. Bundle Registration:

   • For Symfony 5.4+, Flex auto-enables the bundle. For older versions, manually register it in bundles.php or use AppKernel.php.

4. Form Theme Caching:

   • Clear Twig cache after theme modifications:

     php bin/console cache:clear
     

Debugging

• Inspect Rendered HTML: Use {{ dump(form|render|raw) }} in Twig to debug form structure.
• Check for Deprecated Methods: The bundle may rely on Symfony Form components; update if using older Symfony versions.

Extension Points

1. Custom Form Types: Extend the bundle’s theme for custom form types (e.g., ChoiceType):

   {# templates/form/choice_widget.html.twig #}
   {% extends '@EcoheadTailwindFormTheme/form/choice_widget.html.twig' %}
   {% block choice_widget_options %}
       {{ parent() }} class="shadow appearance-none border rounded w-full py-2 px-3"
   {% endblock %}
   

2. Dynamic Theming: Use Twig’s form_theme function to switch themes conditionally:

   {% form_theme form with ['@EcoheadTailwindFormTheme/form/theme.html.twig'] %}
   

3. Symfony 6+ Compatibility: Test with Symfony’s new form component if migrating:

   use Symfony\Component\Form\FormInterface;
   $form->getConfig()->getTheme()->addPath('@EcoheadTailwindFormTheme');