Form Handler Bundle Laravel Package

Getting Started

First Steps

1. Installation Add the bundle to your composer.json:

   composer require byscripts/form-handler-bundle
   

   Enable it in config/bundles.php (Symfony 4+):

   return [
       // ...
       Byscripts\FormHandlerBundle\ByscriptsFormHandlerBundle::class => ['all' => true],
   ];
   

2. Basic Setup

   • Register a form handler in your controller:

     use Byscripts\FormHandlerBundle\Annotation\FormHandler;
     
     class MyController extends AbstractController
     {
         /**
          * @FormHandler("my_form_type")
          */
         public function handleForm(Request $request)
         {
             // Logic here
         }
     }
     

   • Define a form type (MyFormType) extending AbstractType.

3. First Use Case Submit a form and let the bundle handle validation/processing:

   {{ form_start(form) }}
       {{ form_widget(form) }}
       <button type="submit">Submit</button>
   {{ form_end(form) }}
   

   The @FormHandler annotation routes submissions to handleForm().

Implementation Patterns

Workflow Integration

1. Annotation-Driven Routing

   • Use @FormHandler("form_type_name") to bind a form type to a handler method.
   • Example:

     /**
      * @FormHandler("user_registration")
      */
     public function registerUser(Request $request, UserRegistrationForm $form)
     {
         $data = $form->handle($request->request->all());
         // Process $data (e.g., save to DB)
     }
     

2. Form Type Configuration

   • Extend AbstractType and define fields:

     class UserRegistrationForm extends AbstractType
     {
         public function buildForm(FormBuilderInterface $builder, array $options)
         {
             $builder
                 ->add('email', EmailType::class)
                 ->add('password', RepeatedType::class);
         }
     }
     

3. Validation & Processing

   • The bundle auto-validates on submission. Access validated data via $form->handle().
   • Example with custom logic:

     public function handleForm(Request $request, UserRegistrationForm $form)
     {
         $data = $form->handle($request->request->all());
         if ($data['valid']) {
             $user = new User($data['data']);
             $entityManager->persist($user);
         }
         return $this->redirectToRoute('home');
     }
     

4. CSRF & Security

   • Ensure {{ form_start(form) }} includes CSRF protection (default in Symfony forms).
   • For API routes, use form_start(form, {'attr': {'id': 'api-form'}}) and validate manually.

Gotchas and Tips

Pitfalls

1. Deprecated/Obsolete Code

   • Last updated in 2014—expect compatibility issues with modern Symfony/Laravel (if ported).
   • Symfony 4+: May require manual routing or middleware adjustments.

2. Annotation Overhead

   • @FormHandler is annotation-based; if you prefer attributes (PHP 8+), you’ll need to extend the bundle.
   • Alternative: Use a service-based approach (e.g., tagging form handlers).

3. Validation Quirks

   • The bundle assumes Symfony’s ValidatorInterface. For custom validation, inject it manually:

     public function __construct(private ValidatorInterface $validator) {}
     

4. No Laravel Port

   • This is a Symfony bundle, not Laravel-compatible. For Laravel, consider:
     • Laravel Form Request Validation
     • Flysystem + custom middleware.

Debugging Tips

• Check Routes: Ensure @FormHandler routes are registered. Override routing if needed:

  # config/routes.yaml
  _form_handler:
      resource: "@ByscriptsFormHandlerBundle/Resources/config/routing.yml"
  

• Validation Errors: Dump $form->getErrors() in your handler to debug:

  var_dump($form->getErrors()->getIterator());
  

• CSRF Failures: Verify {{ form_start(form) }} is used in templates (not manual HTML).

Extension Points

1. Custom Handlers
   • Extend Byscripts\FormHandlerBundle\Handler\FormHandlerInterface for reusable logic.
2. Event Listeners
   • Subscribe to form.handler.submit events (if the bundle supports them).
3. Alternative: Roll Your Own
   • For Laravel, replace with a middleware-based approach:

     // app/Http/Middleware/HandleFormSubmission.php
     public function handle(Request $request, Closure $next)
     {
         if ($request->isMethod('post') && $request->has('form_type')) {
             $handler = app()->make("form.handler.{$request->input('form_type')}");
             return $handler->process($request);
         }
         return $next($request);
     }