solidworx / form-handler-bundle
Easy form handling for Symfony forms
Installs: 31 120
Dependents: 2
Suggesters: 0
Security: 0
Stars: 6
Watchers: 3
Forks: 1
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=7.1.0
- symfony/event-dispatcher: ^4.4 || ^5.0 || ^6.0 || ^7.0
- symfony/form: ^4.0 || ^5.0 || ^6.0 || ^7.0
- symfony/framework-bundle: ^4.4 || ^5.0 || ^6.0 || ^7.0
- symfony/http-foundation: ^4.4 || ^5.0 || ^6.0 || ^7.0
- symfony/options-resolver: ^4.4 || ^5.0 || ^6.0 || ^7.0
Requires (Dev)
- doctrine/common: ^2.7
- ocramius/proxy-manager: ^2.1
- phpstan/phpstan: ^0.12.8
- symfony/phpunit-bridge: ^5.0
This package is auto-updated.
Last update: 2024-11-11 17:07:24 UTC
README
The FormHandler component attempts to make controllers with basic form handlers cleaner by off-loading form handling to separate classes.
Table of Contents
Requirements
FormHandler requires PHP 7.1+ and Symfony 3.0+
Installation
Composer
$ composer require solidworx/form-handler-bundle:^1.0
Then register the bundle in your Symfony application:
<?php // app/AppKernel.php // ... public function registerBundles() { $bundles = [ // ... new SolidWorx\FormHandler\FormHandlerBundle(), ]; // ... )
Usage
A form can have a class that implements the FormHandlerInterface
interface. This interface exposes a single method in which the form can be retrieved:
public function getForm(FormFactoryInterface $factory, Options $options);
This method can either return a standard form type, or use the factory to generate a form type.
<?php use Symfony\Component\Form\FormFactoryInterface; use SolidWorx\FormHandler\FormHandlerInterface; use SolidWorx\FormHandler\Options; class MyFormHandler implements FormHandlerInterface { public function getForm(FormFactoryInterface $factory, Options $options) { // either return MyFormType::class; // or return $factory->create(MyFormType::class); } }
The benefit of using the factory, is when you need to pass additional information or options to the form, E.G
return $factory->create(MyFormType::class, null, ['horizontal' => true]);
To register your form handler, register it as a service:
services: my.form.handler: class: MyFormHandler tags: - { name: 'form.handler' }
Inside your controller, use the form.handler
service to handle your form:
<?php class MyController extends Controller { public function addAction() { return $this->get('solidworx.form_handler')->handle(MyFormHandler::class); // MyFormHandler will automatically be pulled from the container if it is tagges with `form.handler` } }
This will process the necessary logic on the form (submit the form and handle the request etc).
If you need to handle a failed form, you need to implement the FormHandlerFailInterface
interface:
<?php use SolidWorx\FormHandler\FormRequest; use SolidWorx\FormHandler\FormHandlerInterface; use SolidWorx\FormHandler\FormHandlerFailInterface; use Symfony\Component\Form\FormErrorIterator; class MyFormHandler implements FormHandlerInterface, FormHandlerFailInterface { // ... public function onFail(FormRequest $formRequest, FormErrorIterator $errors, $data = null) { // Form submission has failed, probably due to a validation error. // Handle it here if you need specific custom logic } }
If you need to handle a successful form submission, implement the FormHandlerSuccessInterface
interface:
<?php use SolidWorx\FormHandler\FormRequest; use SolidWorx\FormHandler\FormHandlerInterface; use SolidWorx\FormHandler\FormHandlerSuccessInterface; class MyFormHandler implements FormHandlerInterface, FormHandlerSuccessInterface { // ... public function onSuccess($data, FormRequest $form) { // $data is the submitted data from the form, do something with it here // This will probably save info to the DB } }
Adding options to a form
If you need to pass options to a form, you can add it as an array to the second argument of FormHandler::handle
:
<?php class MyController extends Controller { public function addAction() { return $this->get('solidworx.form_handler')->handle(MyFormHandler::class, ['entity' => new Blog]); // MyFormHandler will automatically be pulled from the container if it is tagges with `form.handler` } }
The options will then be available in the getForm
method as a Options
object:
<?php use Symfony\Component\Form\FormFactoryInterface; use SolidWorx\FormHandler\FormHandlerInterface; use SolidWorx\FormHandler\Options; class MyFormHandler implements FormHandlerInterface { public function getForm(FormFactoryInterface $factory, Options $options) { return $factory->create(MyFormType::class, $options->get('entity')); } }
You can also configure the options to set what options is allowed, set default values, define required options etc. by implementing the FormHandlerOptionsResolver
interface:
<?php use Symfony\Component\OptionsResolver\OptionsResolver; use SolidWorx\FormHandler\FormHandlerInterface; use SolidWorx\FormHandler\FormHandlerOptionsResolver; class MyFormHandler implements FormHandlerInterface, FormHandlerOptionsResolver { // ... public function configureOptions(OptionsResolver $resolver): void { $resolver->setRequired('entity'); $resolver->addAllowedTypes('entity', BlogEntity::class); $resolver->setDefault('another_options', 'myvalue'); } }
Advanced Usage
That is the very basics of the component. There are more advanced usages where you can customize the handling of a form to your specific needs.
Testing
To run the unit tests, execute the following command
$ vendor/bin/phpunit
Contributing
See CONTRIBUTING
License
FormHandler is open-sourced software licensed under the MIT license
Please see the LICENSE file for the full license.