Form Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require amaxlab/form-bundle
   

   Add to config/bundles.php (Symfony 4+):

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

2. Configure reCAPTCHA Register keys in config/packages/amaxlab_form.yaml:

   amaxlab_form:
       recaptcha2:
           public_key: '%env(RECAPTCHA_PUBLIC_KEY)%'
           private_key: '%env(RECAPTCHA_PRIVATE_KEY)%'
   

3. First Use Case: select_or_add

   // src/Form/YourType.php
   use Amaxlab\FormBundle\Form\Type\SelectOrAddType;
   
   $builder->add('entity', SelectOrAddType::class, [
       'class' => YourEntity::class,
       'add_form' => function (FormBuilderInterface $builder, array $options) {
           $builder->add('name', TextType::class);
           $builder->add('save', SubmitType::class);
       },
       'label' => 'Select or add new',
   ]);
   

Implementation Patterns

1. select_or_add Workflow

• Dynamic Entity Selection: Useful for forms where users may need to select an existing entity or create a new one (e.g., user profiles, tags).
• Custom Add Form: Override the nested "add" form via the add_form option to include custom fields or validation.
• Integration with Twig:

  {{ form_row(form.entity) }}
  

  Renders a dropdown + "Add New" button. The "add" modal/form is typically rendered via JavaScript (e.g., using Symfony UX Turbo or Stimulus).

2. reCAPTCHA Integration

• Form Validation: Automatically validates reCAPTCHA responses on submission.
• Placement:

  $builder->add('recaptcha', AmaxlabRecaptcha2Type::class, [
      'mapped' => false,
      'label' => 'Verify you are human',
  ]);
  

• Twig Rendering:

  {{ form_row(form.recaptcha) }}
  

  Renders the reCAPTCHA widget. Ensure the public_key is set in your template (e.g., via data-sitekey).

3. Event-Driven Extensions

• Customize Add Form Logic: Subscribe to amaxlab_form.select_or_add.add_form_builder events to modify the nested form dynamically:

  // src/EventListener/AddFormSubscriber.php
  use Amaxlab\FormBundle\Event\AddFormEvent;
  
  public function onAddFormBuild(AddFormEvent $event) {
      $event->getFormBuilder()->add('custom_field', TextType::class);
  }
  

  Register in services.yaml:

  services:
      App\EventListener\AddFormSubscriber:
          tags:
              - { name: kernel.event_subscriber }
  

Gotchas and Tips

Pitfalls

1. reCAPTCHA Key Mismatch

   • Ensure public_key/private_key match your domain in the reCAPTCHA admin panel. Invalid keys cause silent validation failures.
   • Debug Tip: Check Symfony’s profiler for reCAPTCHA validation errors under the "Validation" tab.

2. JavaScript Dependency for select_or_add

   • The bundle assumes JavaScript is enabled for the "Add New" functionality. Test with JS disabled or provide a fallback (e.g., a link to a separate "create" route).

3. Entity Manager in select_or_add

   • The nested "add" form requires an EntityManager. If using custom repositories or services, ensure they’re autowired into the form type or passed via options:

     $builder->add('entity', SelectOrAddType::class, [
         'entity_manager' => $this->entityManager,
     ]);
     

Debugging Tips

• Validation Errors: Use dump($form->getErrors()) to inspect reCAPTCHA or entity validation issues.
• reCAPTCHA Logs: Enable Guzzle logging in config/packages/guzzle.yaml to debug API calls:

  guzzle:
      plugins:
          - \GuzzleHttp\Subscriber\Log\LogPlugin
  

Extension Points

1. Custom reCAPTCHA Theme Override the Twig template for amaxlab_recaptcha2 in templates/AmaxlabFormBundle/Form/amaxlab_recaptcha2.html.twig.

2. Async reCAPTCHA Validation For better UX, validate reCAPTCHA via AJAX before form submission. Use the bundle’s AmaxlabRecaptchaValidator service directly:

   $validator = $container->get('amaxlab_form.recaptcha_validator');
   $isValid = $validator->validate($response, $publicKey);
   

3. Dynamic select_or_add Options Use the query_builder option to filter entities dynamically:

   $builder->add('entity', SelectOrAddType::class, [
       'query_builder' => function (EntityManagerInterface $em) {
           return $em->createQueryBuilder()
               ->select('e')
               ->from(YourEntity::class, 'e')
               ->where('e.isActive = :active')
               ->setParameter('active', true);
       },
   ]);
   

Configuration Quirks

• Environment Variables: Store reCAPTCHA keys in .env and reference them in config/packages/amaxlab_form.yaml:

  amaxlab_form:
      recaptcha2:
          public_key: '%env(RECAPTCHA_SITE_KEY)%'
          private_key: '%env(RECAPTCHA_SECRET_KEY)%'
  

• Caching: The bundle caches reCAPTCHA responses. Clear the cache (php bin/console cache:clear) if testing locally with the same keys.