Forms Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require artprima/forms-extra-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Artprima\FormsExtraBundle\ArtprimaFormsExtraBundle::class => ['all' => true],
   ];
   

2. First Use Case Extend Symfony’s form system with custom field types or form builders. For example, create a reusable PhoneType field:

   // src/Form/Extension/PhoneTypeExtension.php
   use Symfony\Component\Form\AbstractTypeExtension;
   use Symfony\Component\Form\FormBuilderInterface;
   use Symfony\Component\Form\Extension\Core\Type\TextType;
   
   class PhoneTypeExtension extends AbstractTypeExtension
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->addModelTransformer(new PhoneTransformer());
       }
   
       public function getExtendedType()
       {
           return TextType::class;
       }
   }
   

   Register the extension in services.yaml:

   services:
       App\Form\Extension\PhoneTypeExtension:
           tags: [form.type_extension]
   

3. Key Files to Review

   • src/DependencyInjection/ArtprimaFormsExtraExtension.php (Configuration)
   • src/Resources/config/services.yaml (Default services)

Implementation Patterns

Common Workflows

1. Custom Field Types Extend existing types (e.g., TextType, ChoiceType) by creating a TypeExtension or a standalone AbstractType. Example:

   // src/Form/Type/CustomEmailType.php
   class CustomEmailType extends AbstractType
   {
       public function buildForm(FormBuilderInterface $builder, array $options)
       {
           $builder->addModelTransformer(new CustomEmailTransformer());
       }
   
       public function configureOptions(OptionsResolver $resolver)
       {
           $resolver->setDefaults(['required' => true]);
       }
   }
   

2. Form Events Leverage Symfony’s form events (e.g., PRE_SET_DATA, POST_SUBMIT) for dynamic behavior:

   // src/Form/EventListener/CustomFormListener.php
   class CustomFormListener implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               FormEvents::PRE_SET_DATA => 'onPreSetData',
           ];
       }
   
       public function onPreSetData(FormEvent $event)
       {
           $data = $event->getData();
           // Custom logic here
       }
   }
   

3. Integration with Doctrine Use DataTransformer to sync form data with Doctrine entities:

   // src/Form/DataTransformer/EntityToIdTransformer.php
   class EntityToIdTransformer implements DataTransformerInterface
   {
       public function transform($entity)
       {
           return $entity ? $entity->getId() : null;
       }
   
       public function reverseTransform($id)
       {
           return $entityManager->find(Entity::class, $id);
       }
   }
   

Best Practices

• Namespace Conflicts: Prefix custom types/extensions (e.g., App\Form\Type\CustomType).
• Configuration: Use config/packages/artprima_forms_extra.yaml for bundle-specific settings.
• Testing: Mock form builders and events in PHPUnit tests:

  $formBuilder = $this->createMock(FormBuilderInterface::class);
  $event = new FormEvent($formBuilder, new TestRequest(), []);
  $listener->onPreSetData($event);
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch The bundle requires PHP 5.3.3+, but modern Symfony (5.4+) uses PHP 7.4+. Test compatibility or fork the bundle.

2. Doctrine Dependency The doctrine/orm requirement may cause conflicts if not using Doctrine. Exclude it in composer.json:

   "require": {
       "doctrine/orm": ">=2.2.3|null"
   }
   

3. No Official Support The README states "No support will be provided ever." Proceed with caution or fork/extend the bundle.

4. Monolog Bundle Dependency The symfony/monolog-bundle requirement is unused in the bundle. Remove it if not needed:

   composer remove symfony/monolog-bundle
   

Debugging Tips

• Form Errors: Enable Symfony’s profiler (APP_DEBUG=true) to inspect form errors.
• Transformer Issues: Validate transform()/reverseTransform() methods return expected types (e.g., null vs. false).
• Event Order: Use EventDispatcher::addSubscriber() with priority to control event execution order.

Extension Points

1. Custom Form Themes Override Twig templates in templates/form/ (e.g., form_div_layout.html.twig).

2. Dynamic Options Use OptionsResolver callbacks for runtime option validation:

   $resolver->setAllowedTypes('custom_option', 'string');
   $resolver->setDefault('custom_option', 'default_value');
   

3. Validation Groups Integrate with Symfony Validator:

   $builder->add('field', TextType::class, [
       'constraints' => [
           new NotBlank(),
           new Length(['min' => 3]),
       ],
   ]);
   

4. CSRF Protection Ensure forms include {{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }} if using custom validation.