Skip to content
Easy form handling for Symfony forms
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
tests
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE
README.md
composer.json
phpunit.xml.dist

README.md

FormHandlerBundle

Build Status

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.

You can’t perform that action at this time.