Form Handler Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require chaplean/form-handler-bundle
   

   Add the bundle to config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Chaplean\FormHandlerBundle\ChapleanFormHandlerBundle::class => ['all' => true],
   

2. First Use Case Inject the FormHandler service into a controller and use it to handle form submissions:

   use Symfony\Component\HttpFoundation\Request;
   
   public function createAction(Request $request)
   {
       return $this->get('chaplean_form_handler.form_handler')
           ->handle(UserType::class, new User(), $request);
   }
   

3. Key Files to Review

   • src/Chaplean/FormHandlerBundle/DependencyInjection/Configuration.php (for config options).
   • src/Chaplean/FormHandlerBundle/Form/FormHandler.php (core logic).
   • src/Chaplean/FormHandlerBundle/Resources/config/services.xml (service definitions).

Implementation Patterns

Core Workflow

1. Form Handling Use handle() to process requests with a form type and entity:

   $handler = $this->get('chaplean_form_handler.form_handler');
   $response = $handler->handle(
       FormType::class,       // Form type class
       $entity,              // Entity instance (new or existing)
       $request,             // Request object
       ['group' => 'default'] // Optional options
   );
   

2. Integration with FOSRestBundle Leverage annotations for RESTful endpoints:

   use FOS\RestBundle\Controller\Annotations\RouteResource;
   
   /**
    * @RouteResource("User")
    */
   class UserController extends FOSRestController
   {
       public function postAction(Request $request)
       {
           return $this->get('chaplean_form_handler.form_handler')
               ->handle(UserType::class, new User(), $request);
       }
   }
   

3. Customizing Responses Override default serialization groups or error formats:

   $handler->handle(
       UserType::class,
       $user,
       $request,
       [
           'serialization_groups' => ['public'],
           'error_format' => 'api_platform'
       ]
   );
   

4. Event Listeners Attach listeners to modify behavior (e.g., pre/post-processing):

   # config/services.yaml
   services:
       App\EventListener\CustomFormListener:
           tags:
               - { name: chaplean_form_handler.listener }
   

Common Patterns

• Dynamic Entity Handling: Pass new/existing entities to handle() for create/update logic.
• Request Validation: Automatically validates and converts form errors to API-friendly formats.
• Serialization: Uses Symfony Serializer for responses (configure via serialization_groups).

Gotchas and Tips

Pitfalls

1. Missing Form Type Ensure the form type class (e.g., UserType) is registered with Symfony’s form system. Use:

   $builder->add('name', TextType::class);
   

2. Entity Not Persisted By default, the handler does not persist entities. Manually flush or configure auto-persist:

   $handler->handle(..., $request, ['auto_persist' => true]);
   

3. Serialization Groups If responses are empty, verify serialization_groups are defined in your entity’s @Groups annotations.

4. Request Binding The handler expects Request objects with JSON/XML payloads. For HTML forms, use Request::get() or Request::request.

Debugging Tips

• Enable Form Debugging Add to config/packages/dev/form.yaml:

  framework:
      form: { enabled: true }
  

• Check Listener Order If listeners conflict, adjust their priority in the tags configuration.

Extension Points

1. Custom Error Formats Override the default error formatter by implementing Chaplean\FormHandlerBundle\Error\ErrorFormatterInterface.

2. Pre/Post-Processing Use event listeners (chaplean_form_handler.listener) to:

   • Modify entities before handling.
   • Add custom logic post-validation.

3. Configuration Override default settings in config/packages/chaplean_form_handler.yaml:

   chaplean_form_handler:
       default_options:
           auto_persist: false
           serialization_groups: ['default']
   

4. Testing Mock the FormHandler service in tests:

   $handler = $this->createMock(FormHandler::class);
   $handler->method('handle')->willReturn($response);
   $this->container->set('chaplean_form_handler.form_handler', $handler);