Important

You are browsing documentation for version 5.0 of OroCommerce, supported until January 2025. Read the documentation for version 6.0 (the latest LTS version) to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Update Handler

Form Handler Events

Default form handler Oro\Bundle\FormBundle\Model\FormHandler triggers events that enables you to modify processing data or even stop form processing.

There are two type of events:

• FormProcessEvent (Oro\Bundle\FormBundle\Event\FormHandler\FormProcessEvent) - triggered during form processing, can stop further form processing via interruptFormProcess method.

• AfterFormProcessEvent (Oro\Bundle\FormBundle\Event\FormHandler\FormProcessEvent) - triggered after form processing during saving of form data.

And there are four events triggered in form handler:

• BEFORE_FORM_DATA_SET (Oro\Bundle\FormBundle\Event\FormHandler\Events::BEFORE_FORM_DATA_SET) - uses FormProcessEvent, triggered in the very beginning of form processing right before input data set to form instance.

• BEFORE_FORM_SUBMIT (Oro\Bundle\FormBundle\Event\FormHandler\Events::BEFORE_FORM_SUBMIT) - uses FormProcessEvent, triggered only for valid form methods (POST or PUT) before request submitting to form instance.

• BEFORE_FLUSH (Oro\Bundle\FormBundle\Event\FormHandler\Events::BEFORE_FLUSH) - uses AfterFormProcessEvent, triggered right before flushing of object manager.

• AFTER_FLUSH (Oro\Bundle\FormBundle\Event\FormHandler\Events::AFTER_FLUSH) - uses AfterFormProcessEvent, triggered right after flushing of object manager.

To use a custom form handler, trigger these events in the custom handler to support form processing consistency.

Update Handler Facade Service

Service: @oro_form.update_handler

Class: Oro\Bundle\FormBundle\Model\UpdateHandlerFacade

The default common way to handle forms in Oro packages is to use the Oro\Bundle\FormBundle\Model\UpdateHandlerFacade::update method from the service with your custom arguments provided.

Among usual arguments, there are two most valuable from the point of reuse.

The handler - for custom handler purpose:

• string - an alias of registered by tag oro_form.form.handler Oro\Bundle\FormBundle\Form\Handler\FormHandlerInterface implementation service

• callable - a callback to perform handling (see FormHandlerInterface::process() for arguments)

• Oro\Bundle\FormBundle\Form\Handler\FormHandlerInterface - an instance of the handler itself

• null - to use default registered under tag oro_form.form.handler handler service that implements interface above

The dataProvider - for custom template data purpose:

@param FormTemplateDataProviderInterface|string|callable|null $resultProvider to provide template data

• string - an alias of registered by tag oro_form.form_template_data_provider service that implements Oro\Bundle\FormBundle\Form\Handler\FormHandlerInterface

• callable - callback to provide data (see FormTemplateDataProviderInterface::getData() for arguments)

• Oro\Bundle\FormBundle\Provider\FormTemplateDataProviderInterface - an instance of provider itself

• null - to use default registered provider (usually it returns [‘form’ => FormView $instance])

Custom TemplateDataProvider and FormHandler can be reused in different parts of platform, such as WorkflowBundle Custom Form Configuration.

Example of custom handler and data provider services registration and usage:

Services:

services:
   my_bundle.form.user_handler:
       class: MyBundle\Form\UserHandler
       tags:
           - { name: oro_form.form.handler, alias: user_handler }
   my_bundle.form.user_update_data_provider:
       class: MyBundle\Form\UserUpdateDataProvider
       public: false
       tags:
           - { name: oro_form.form_template_data_provider, alias: user_update_data }

A pseudo controller:

class UserController {
   public function createAction(Request $request)
   {
       return $this->get('oro_form.update_handler')->update(
           new User(),
           $this->get('form_factory')->create(\MyBundle\Form\UserType::class),
           'Success! User created!',
           $request,
           'user_handler', //using an alias tagged my_bundle.form.user_handler service
           'user_update_data' //using an alias tagged my_bundle.form.user_update_data_provider service
       );
   }
}

The separation of responsibilities above (such as division of usual controller update process parts) is a powerful feature that can help you use all OroPlatform-based functionality easier.