The Form Component

The Form Component

The Form component allows you to create, process and reuse forms.

The Form component is a tool to help you solve the problem of allowing end-usersto interact with the data and modify the data in your application. And thoughtraditionally this has been through HTML forms, the component focuses onprocessing data to and from your client and application, whether that databe from a normal form post or from an API.

Installation

$ composer require symfony/form

Note

If you install this component outside of a Symfony application, you mustrequire the vendor/autoload.php file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

Configuration

This article explains how to use the Form features as an independentcomponent in any PHP application. Read the Forms article to learnabout how to use it in Symfony applications.

In Symfony, forms are represented by objects and these objects are builtby using a form factory. Building a form factory is done with the factorymethod Forms::createFormFactory:

use Symfony\Component\Form\Forms;
 
$formFactory = Forms::createFormFactory();

This factory can already be used to create basic forms, but it is lackingsupport for very important features:

Request Handling: Support for request handling and file uploads;
CSRF Protection: Support for protection against Cross-Site-Request-Forgery(CSRF) attacks;
Templating: Integration with a templating layer that allows you to reuseHTML fragments when rendering a form;
Translation: Support for translating error messages, field labels andother strings;
Validation: Integration with a validation library to generate errormessages for submitted data.The Symfony Form component relies on other libraries to solve these problems.Most of the time you will use Twig and the SymfonyHttpFoundation,Translation and Validatorcomponents, but you can replace any of these with a different library of your choice.

The following sections explain how to plug these libraries into the formfactory.

Tip

For a working example, see https://github.com/webmozart/standalone-forms

Request Handling

To process form data, you'll need to call the handleRequest()method:

$form->handleRequest();

Behind the scenes, this uses a NativeRequestHandlerobject to read data off of the correct PHP superglobals (i.e. $_POST or$_GET) based on the HTTP method configured on the form (POST is default).

If you need more control over exactly when your form is submitted or whichdata is passed to it,use the submit() method to handle form submissions.

Integration with the HttpFoundation Component

If you use the HttpFoundation component, then you should add theHttpFoundationExtensionto your form factory:

use Symfony\Component\Form\Extension\HttpFoundation\HttpFoundationExtension;
use Symfony\Component\Form\Forms;
 
$formFactory = Forms::createFormFactoryBuilder()
    ->addExtension(new HttpFoundationExtension())
    ->getFormFactory();

Now, when you process a form, you can pass the Requestobject to handleRequest():

$form->handleRequest($request);

Note

For more information about the HttpFoundation component or how toinstall it, see The HttpFoundation Component.

CSRF Protection

Protection against CSRF attacks is built into the Form component, but you needto explicitly enable it or replace it with a custom solution. If you want touse the built-in support, first install the Security CSRF component:

$ composer require symfony/security-csrf

The following snippet adds CSRF protection to the form factory:

use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
use Symfony\Component\Form\Forms;
use Symfony\Component\HttpFoundation\Session\Session;
use Symfony\Component\Security\Csrf\CsrfTokenManager;
use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
 
// creates a Session object from the HttpFoundation component
$session = new Session();
 
$csrfGenerator = new UriSafeTokenGenerator();
$csrfStorage = new SessionTokenStorage($session);
$csrfManager = new CsrfTokenManager($csrfGenerator, $csrfStorage);
 
$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->addExtension(new CsrfExtension($csrfManager))
    ->getFormFactory();

Internally, this extension will automatically add a hidden field to everyform (called _token by default) whose value is automatically generated bythe CSRF generator and validated when binding the form.

Tip

If you're not using the HttpFoundation component, you can useNativeSessionTokenStorageinstead, which relies on PHP's native session handling:

use Symfony\Component\Security\Csrf\TokenStorage\NativeSessionTokenStorage;
 
$csrfStorage = new NativeSessionTokenStorage();
// ...

You can disable CSRF protection per form using the csrf_protection option:

use Symfony\Component\Form\Extension\Core\Type\FormType;
 
$form = $formFactory->createBuilder(FormType::class, null, ['csrf_protection' => false])
    ->getForm();

Twig Templating

If you're using the Form component to process HTML forms, you'll need a way torender your form as HTML form fields (complete with field values, errors, andlabels). If you use Twig as your template engine, the Form component offers arich integration.

To use the integration, you'll need the twig bridge, which provides integrationbetween Twig and several Symfony components:

$ composer require symfony/twig-bridge

The TwigBridge integration provides you with severalTwig Functionsthat help you render the HTML widget, label, help and errors for each field(as well as a few other things). To configure the integration, you'll needto bootstrap or access Twig and add the FormExtension:

use Symfony\Bridge\Twig\Extension\FormExtension;
use Symfony\Bridge\Twig\Form\TwigRendererEngine;
use Symfony\Component\Form\FormRenderer;
use Symfony\Component\Form\Forms;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;
use Twig\RuntimeLoader\FactoryRuntimeLoader;
 
// the Twig file that holds all the default markup for rendering forms
// this file comes with TwigBridge
$defaultFormTheme = 'form_div_layout.html.twig';
 
$vendorDirectory = realpath(__DIR__.'/../vendor');
// the path to TwigBridge library so Twig can locate the
// form_div_layout.html.twig file
$appVariableReflection = new \ReflectionClass('\Symfony\Bridge\Twig\AppVariable');
$vendorTwigBridgeDirectory = dirname($appVariableReflection->getFileName());
// the path to your other templates
$viewsDirectory = realpath(__DIR__.'/../views');
 
$twig = new Environment(new FilesystemLoader([
    $viewsDirectory,
    $vendorTwigBridgeDirectory.'/Resources/views/Form',
]));
$formEngine = new TwigRendererEngine([$defaultFormTheme], $twig);
$twig->addRuntimeLoader(new FactoryRuntimeLoader([
    FormRenderer::class => function () use ($formEngine, $csrfManager) {
        return new FormRenderer($formEngine, $csrfManager);
    },
]));
 
// ... (see the previous CSRF Protection section for more information)
 
// adds the FormExtension to Twig
$twig->addExtension(new FormExtension());
 
// creates a form factory
$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->getFormFactory();

New in version 1.30: The Twig\RuntimeLoader\FactoryRuntimeLoader was introduced in Twig 1.30.

The exact details of your Twig Configuration will vary, but the goal isalways to add the FormExtensionto Twig, which gives you access to the Twig functions for rendering forms.To do this, you first need to create a TwigRendererEngine,where you define your form themes(i.e. resources/files that define form HTML markup).

For general details on rendering forms, see How to Customize Form Rendering.

Note

If you use the Twig integration, read "Translation"below for details on the needed translation filters.

Translation

If you're using the Twig integration with one of the default form theme files(e.g. form_div_layout.html.twig), there are 2 Twig filters (transand transChoice) that are used for translating form labels, errors, optiontext and other strings.

To add these Twig filters, you can either use the built-inTranslationExtension that integrateswith Symfony's Translation component, or add the 2 Twig filters yourself,via your own Twig extension.

To use the built-in integration, be sure that your project has Symfony'sTranslation and Config componentsinstalled:

$ composer require symfony/translation symfony/config

Next, add the TranslationExtensionto your Twig\Environment instance:

use Symfony\Bridge\Twig\Extension\TranslationExtension;
use Symfony\Component\Form\Forms;
use Symfony\Component\Translation\Loader\XliffFileLoader;
use Symfony\Component\Translation\Translator;
 
// creates the Translator
$translator = new Translator('en');
// somehow load some translations into it
$translator->addLoader('xlf', new XliffFileLoader());
$translator->addResource(
    'xlf',
    __DIR__.'/path/to/translations/messages.en.xlf',
    'en'
);
 
// adds the TranslationExtension (gives us trans and transChoice filters)
$twig->addExtension(new TranslationExtension($translator));
 
$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->getFormFactory();

Depending on how your translations are being loaded, you can now add stringkeys, such as field labels, and their translations to your translation files.

For more details on translations, see Translations.

Validation

The Form component comes with tight (but optional) integration with Symfony'sValidator component. If you're using a different solution for validation,no problem! Take the submitted/bound data of your form (which is anarray or object) and pass it through your own validation system.

To use the integration with Symfony's Validator component, first make sureit's installed in your application:

$ composer require symfony/validator

If you're not familiar with Symfony's Validator component, read more aboutit: Validation. The Form component comes with aValidatorExtensionclass, which automatically applies validation to your data on bind. Theseerrors are then mapped to the correct field and rendered.

Your integration with the Validation component will look something like this:

use Symfony\Component\Form\Extension\Validator\ValidatorExtension;
use Symfony\Component\Form\Forms;
use Symfony\Component\Validator\Validation;
 
$vendorDirectory = realpath(__DIR__.'/../vendor');
$vendorFormDirectory = $vendorDirectory.'/symfony/form';
$vendorValidatorDirectory = $vendorDirectory.'/symfony/validator';
 
// creates the validator - details will vary
$validator = Validation::createValidator();
 
// there are built-in translations for the core error messages
$translator->addResource(
    'xlf',
    $vendorFormDirectory.'/Resources/translations/validators.en.xlf',
    'en',
    'validators'
);
$translator->addResource(
    'xlf',
    $vendorValidatorDirectory.'/Resources/translations/validators.en.xlf',
    'en',
    'validators'
);
 
$formFactory = Forms::createFormFactoryBuilder()
    // ...
    ->addExtension(new ValidatorExtension($validator))
    ->getFormFactory();

To learn more, skip down to the Form Validation section.

Accessing the Form Factory

Your application only needs one form factory, and that one factory objectshould be used to create any and all form objects in your application. Thismeans that you should create it in some central, bootstrap part of your applicationand then access it whenever you need to build a form.

Note

In this document, the form factory is always a local variable called$formFactory. The point here is that you will probably need to createthis object in some more "global" way so you can access it from anywhere.

Exactly how you gain access to your one form factory is up to you. If you'reusing a service container (like provided with theDependencyInjection component),then you should add the form factory to your container and grab it out wheneveryou need to. If your application uses global or static variables (not usually agood idea), then you can store the object on some static class or do somethingsimilar.

Regardless of how you architect your application, remember that youshould only have one form factory and that you'll need to be able to accessit throughout your application.

Creating a simple Form

Tip

If you're using the Symfony Framework, then the form factory is availableautomatically as a service called form.factory. Also, the defaultbase controller class has a createFormBuilder()method, which is a shortcut to fetch the form factory and call createBuilder()on it.

Creating a form is done via a FormBuilderobject, where you build and configure different fields. The form builderis created from the form factory.

Standalone Use

use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
 
// ...
 
$form = $formFactory->createBuilder()
    ->add('task', TextType::class)
    ->add('dueDate', DateType::class)
    ->getForm();
 
var_dump($twig->render('new.html.twig', [
    'form' => $form->createView(),
]));

Framework Use

// src/Controller/TaskController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
 
class TaskController extends AbstractController
{
    public function new(Request $request)
    {
        // createFormBuilder is a shortcut to get the "form factory"
        // and then call "createBuilder()" on it
 
        $form = $this->createFormBuilder()
            ->add('task', TextType::class)
            ->add('dueDate', DateType::class)
            ->getForm();
 
        return $this->render('task/new.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

As you can see, creating a form is like writing a recipe: you call add()for each new field you want to create. The first argument to add() is thename of your field, and the second is the fully qualified class name. The Formcomponent comes with a lot of built-in types.

Now that you've built your form, learn how to renderit and process the form submission.

Setting default Values

If you need your form to load with some default values (or you're buildingan "edit" form), pass in the default data when creating your form builder:

Standalone Use

use Symfony\Component\Form\Extension\Core\Type\FormType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
 
// ...
 
$defaults = [
    'dueDate' => new \DateTime('tomorrow'),
];
 
$form = $formFactory->createBuilder(FormType::class, $defaults)
    ->add('task', TextType::class)
    ->add('dueDate', DateType::class)
    ->getForm();

Framework Use

// src/Controller/DefaultController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
 
class DefaultController extends AbstractController
{
    public function new(Request $request)
    {
        $defaults = [
            'dueDate' => new \DateTime('tomorrow'),
        ];
 
        $form = $this->createFormBuilder($defaults)
            ->add('task', TextType::class)
            ->add('dueDate', DateType::class)
            ->getForm();
 
        // ...
    }
}

Tip

In this example, the default data is an array. Later, when you use thedata_class option to bind data directly toobjects, your default data will be an instance of that object.

Rendering the Form

Now that the form has been created, the next step is to render it. This isdone by passing a special form "view" object to your template (notice the$form->createView() in the controller above) and using a set ofform helper functions:

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

That's it! By printing formwidget(form), each field in the form isrendered, along with a label and error message (if there is one). While this isconvenient, it's not very flexible (yet). Usually, you'll want to render eachform field individually so you can control how the form looks. You'll learn howto do that in the [_form customization](https://symfony.com/doc/current/form/form_customization.html) article.

Changing a Form's Method and Action

By default, a form is submitted to the same URI that rendered the form withan HTTP POST request. This behavior can be changed using the actionand method options (the method option is also usedby handleRequest() to determine whether a form has been submitted):

Standalone Use

use Symfony\Component\Form\Extension\Core\Type\FormType;
 
// ...
 
$formBuilder = $formFactory->createBuilder(FormType::class, null, [
    'action' => '/search',
    'method' => 'GET',
]);
 
// ...

Framework Use

// src/Controller/DefaultController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\Extension\Core\Type\FormType;
 
class DefaultController extends AbstractController
{
    public function search()
    {
        $formBuilder = $this->createFormBuilder(null, [
            'action' => '/search',
            'method' => 'GET',
        ]);
 
        // ...
    }
}

Handling Form Submissions

To handle form submissions, use the handleRequest()method:

Standalone Use

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
 
// ...
 
$form = $formFactory->createBuilder()
    ->add('task', TextType::class)
    ->add('dueDate', DateType::class)
    ->getForm();
 
$request = Request::createFromGlobals();
 
$form->handleRequest($request);
 
if ($form->isSubmitted() && $form->isValid()) {
    $data = $form->getData();
 
    // ... perform some action, such as saving the data to the database
 
    $response = new RedirectResponse('/task/success');
    $response->prepare($request);
 
    return $response->send();
}
 
// ...

Framework Use

// src/Controller/TaskController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
 
class TaskController extends AbstractController
{
    public function new(Request $request)
    {
        $form = $this->createFormBuilder()
            ->add('task', TextType::class)
            ->add('dueDate', DateType::class)
            ->getForm();
 
        $form->handleRequest($request);
 
        if ($form->isSubmitted() && $form->isValid()) {
            $data = $form->getData();
 
            // ... perform some action, such as saving the data to the database
 
            return $this->redirectToRoute('task_success');
        }
 
        // ...
    }
}

This defines a common form "workflow", which contains 3 different possibilities:

On the initial GET request (i.e. when the user "surfs" to your page),build your form and render it;If the request is a POST, process the submitted data (via handleRequest()).Then:
if the form is invalid, re-render the form (which will now contain errors);
if the form is valid, perform some action and redirect.Luckily, you don't need to decide whether or not a form has been submitted.Pass the current request to the handleRequest() method. Then, the Formcomponent will do all the necessary work for you.

Form Validation

The easiest way to add validation to your form is via the constraintsoption when building each field:

Standalone Use

use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Type;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
 
$form = $formFactory->createBuilder()
    ->add('task', TextType::class, [
        'constraints' => new NotBlank(),
    ])
    ->add('dueDate', DateType::class, [
        'constraints' => [
            new NotBlank(),
            new Type(\DateTime::class),
        ]
    ])
    ->getForm();

Framework Use

// src/Controller/DefaultController.php
namespace App\Controller;
 
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Type;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
 
class DefaultController extends AbstractController
{
    public function new(Request $request)
    {
        $form = $this->createFormBuilder()
            ->add('task', TextType::class, [
                'constraints' => new NotBlank(),
            ])
            ->add('dueDate', DateType::class, [
                'constraints' => [
                    new NotBlank(),
                    new Type(\DateTime::class),
                ]
            ])
            ->getForm();
        // ...
    }
}

When the form is bound, these validation constraints will be applied automaticallyand the errors will display next to the fields on error.

Note

For a list of all of the built-in validation constraints, seeValidation Constraints Reference.

Accessing Form Errors

You can use the getErrors()method to access the list of errors. It returns aFormErrorIterator instance:

$form = ...;
 
// ...
 
// a FormErrorIterator instance, but only errors attached to this
// form level (e.g. global errors)
$errors = $form->getErrors();
 
// a FormErrorIterator instance, but only errors attached to the
// "firstName" field
$errors = $form['firstName']->getErrors();
 
// a FormErrorIterator instance in a flattened structure
// use getOrigin() to determine the form causing the error
$errors = $form->getErrors(true);
 
// a FormErrorIterator instance representing the form tree structure
$errors = $form->getErrors(true, false);

Clearing Form Errors

Any errors can be manually cleared using theclearErrors()method. This is useful when you'd like to validate the form without showingvalidation errors to the user (i.e. during a partial AJAX submission ordynamic form modification).

Because clearing the errors makes the form valid, clearErrors() should onlybe called after testing whether the form is valid.

Form

The Form Component

Installation

Configuration

Request Handling

CSRF Protection

Twig Templating

Translation

Validation

Accessing the Form Factory

Creating a simple Form

Setting default Values

Rendering the Form

Changing a Form's Method and Action

Handling Form Submissions

Form Validation

Accessing Form Errors

Clearing Form Errors

Learn more