Forms

Warning: You are browsing the documentation for Symfony 5.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.2 (the current stable version).

Screencast

Do you prefer video tutorials? Check out the Symfony Forms screencast series.

Creating and processing HTML forms is hard and repetitive. You need to deal with rendering HTML form fields, validating submitted data, mapping the form data into objects and a lot more. Symfony includes a powerful form feature that provides all these features and many more for truly complex scenarios.

Installation

In applications using Symfony Flex, run this command to install the form feature before using it:

1
$ composer require symfony/form

Usage

The recommended workflow when working with Symfony forms is the following:

  1. Build the form in a Symfony controller or using a dedicated form class;
  2. Render the form in a template so the user can edit and submit it;
  3. Process the form to validate the submitted data, transform it into PHP data and do something with it (e.g. persist it in a database).

Each of these steps is explained in detail in the next sections. To make examples easier to follow, all of them assume that you're building a small Todo list application that displays "tasks".

Users create and edit tasks using Symfony forms. Each task is an instance of the following Task class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// src/Entity/Task.php
namespace App\Entity;

class Task
{
    protected $task;
    protected $dueDate;

    public function getTask(): string
    {
        return $this->task;
    }

    public function setTask(string $task): void
    {
        $this->task = $task;
    }

    public function getDueDate(): ?\DateTime
    {
        return $this->dueDate;
    }

    public function setDueDate(?\DateTime $dueDate): void
    {
        $this->dueDate = $dueDate;
    }
}

This class is a "plain-old-PHP-object" because, so far, it has nothing to do with Symfony or any other library. It's a normal PHP object that directly solves a problem inside your application (i.e. the need to represent a task in your application). But you can also edit Doctrine entities in the same way.

Form Types

Before creating your first Symfony form, it's important to understand the concept of "form type". In other projects, it's common to differentiate between "forms" and "form fields". In Symfony, all of them are "form types":

  • a single <input type="text"> form field is a "form type" (e.g. TextType);
  • a group of several HTML fields used to input a postal address is a "form type" (e.g. PostalAddressType);
  • an entire <form> with multiple fields to edit a user profile is a "form type" (e.g. UserProfileType).

This may be confusing at first, but it will feel natural to you soon enough. Besides, it simplifies code and makes "composing" and "embedding" form fields much easier to implement.

There are tens of form types provided by Symfony and you can also create your own form types.

Tip

You can use the debug:form to list all the available types, type extensions and type guessers in your application:

1
2
3
4
5
6
7
8
$ php bin/console debug:form

# pass the form type FQCN to only show the options for that type, its parents and extensions.
# For built-in types, you can pass the short classname instead of the FQCN
$ php bin/console debug:form BirthdayType

# pass also an option name to only display the full definition of that option
$ php bin/console debug:form BirthdayType label_attr

Building Forms

Symfony provides a "form builder" object which allows you to describe the form fields using a fluent interface. Later, this builder creates the actual form object used to render and process contents.

Creating Forms in Controllers

If your controller extends from the AbstractController, use the createFormBuilder() helper:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// src/Controller/TaskController.php
namespace App\Controller;

use App\Entity\Task;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class TaskController extends AbstractController
{
    public function new(Request $request): Response
    {
        // creates a task object and initializes some data for this example
        $task = new Task();
        $task->setTask('Write a blog post');
        $task->setDueDate(new \DateTime('tomorrow'));

        $form = $this->createFormBuilder($task)
            ->add('task', TextType::class)
            ->add('dueDate', DateType::class)
            ->add('save', SubmitType::class, ['label' => 'Create Task'])
            ->getForm();

        // ...
    }
}

If your controller does not extend from AbstractController, you'll need to fetch services in your controller and use the createBuilder() method of the form.factory service.

In this example, you've added two fields to your form - task and dueDate - corresponding to the task and dueDate properties of the Task class. You've also assigned each a form type (e.g. TextType and DateType), represented by its fully qualified class name. Finally, you added a submit button with a custom label for submitting the form to the server.

Creating Form Classes

Symfony recommends putting as little logic as possible in controllers. That's why it's better to move complex forms to dedicated classes instead of defining them in controller actions. Besides, forms defined in classes can be reused in multiple actions and services.

Form classes are form types that implement FormTypeInterface. However, it's better to extend from AbstractType, which already implements the interface and provides some utilities:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// src/Form/Type/TaskType.php
namespace App\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('task', TextType::class)
            ->add('dueDate', DateType::class)
            ->add('save', SubmitType::class)
        ;
    }
}

Tip

Install the MakerBundle in your project to generate form classes using the make:form and make:registration-form commands.

The form class contains all the directions needed to create the task form. In controllers extending from the AbstractController, use the createForm() helper (otherwise, use the create() method of the form.factory service):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// src/Controller/TaskController.php
namespace App\Controller;

use App\Form\Type\TaskType;
// ...

class TaskController extends AbstractController
{
    public function new(): Response
    {
        // creates a task object and initializes some data for this example
        $task = new Task();
        $task->setTask('Write a blog post');
        $task->setDueDate(new \DateTime('tomorrow'));

        $form = $this->createForm(TaskType::class, $task);

        // ...
    }
}

Every form needs to know the name of the class that holds the underlying data (e.g. App\Entity\Task). Usually, this is just guessed based off of the object passed to the second argument to createForm() (i.e. $task). Later, when you begin embedding forms, this will no longer be sufficient.

So, while not always necessary, it's generally a good idea to explicitly specify the data_class option by adding the following to your form type class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// src/Form/Type/TaskType.php
namespace App\Form\Type;

use App\Entity\Task;
use Symfony\Component\OptionsResolver\OptionsResolver;
// ...

class TaskType extends AbstractType
{
    // ...

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'data_class' => Task::class,
        ]);
    }
}

Rendering Forms

Now that the form has been created, the next step is to render it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// src/Controller/TaskController.php
namespace App\Controller;

use App\Entity\Task;
use App\Form\Type\TaskType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class TaskController extends AbstractController
{
    public function new(Request $request): Response
    {
        $task = new Task();
        // ...

        $form = $this->createForm(TaskType::class, $task);

        return $this->renderForm('task/new.html.twig', [
            'form' => $form,
        ]);
    }
}

In versions prior to Symfony 5.3, controllers used the method $this->render('...', ['form' => $form->createView()]) to render the form. The renderForm() method abstracts this logic and it also sets the 422 HTTP status code in the response automatically when the submitted form is not valid.

5.3

The renderForm() method was introduced in Symfony 5.3.

Then, use some form helper functions to render the form contents:

1
2
{# templates/task/new.html.twig #}
{{ form(form) }}

That's it! The form() function renders all fields and the <form> start and end tags. By default, the form method is POST and the target URL is the same that displayed the form, but you can change both.

Notice how the rendered task input field has the value of the task property from the $task object (i.e. "Write a blog post"). This is the first job of a form: to take data from an object and translate it into a format that's suitable for being rendered in an HTML form.

Tip

The form system is smart enough to access the value of the protected task property via the getTask() and setTask() methods on the Task class. Unless a property is public, it must have a "getter" and "setter" method so that Symfony can get and put data onto the property. For a boolean property, you can use an "isser" or "hasser" method (e.g. isPublished() or hasReminder()) instead of a getter (e.g. getPublished() or getReminder()).

As short as this rendering is, it's not very flexible. Usually, you'll need more control about how the entire form or some of its fields look. For example, thanks to the Bootstrap 5 integration with Symfony forms you can set this option to generate forms compatible with the Bootstrap 5 CSS framework:

1
2
3
# config/packages/twig.yaml
twig:
    form_themes: ['bootstrap_5_layout.html.twig']

The built-in Symfony form themes include Bootstrap 3, 4 and 5, Foundation 5 and 6, as well as Tailwind 2. You can also create your own Symfony form theme.

In addition to form themes, Symfony allows you to customize the way fields are rendered with multiple functions to render each field part separately (widgets, labels, errors, help messages, etc.)

Processing Forms

The recommended way of processing forms is to use a single action for both rendering the form and handling the form submit. You can use separate actions, but using one action simplifies everything while keeping the code concise and maintainable.

Processing a form means to translate user-submitted data back to the properties of an object. To make this happen, the submitted data from the user must be written into the form object:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// src/Controller/TaskController.php

// ...
use Symfony\Component\HttpFoundation\Request;

class TaskController extends AbstractController
{
    public function new(Request $request): Response
    {
        // just set up a fresh $task object (remove the example data)
        $task = new Task();

        $form = $this->createForm(TaskType::class, $task);

        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            // $form->getData() holds the submitted values
            // but, the original `$task` variable has also been updated
            $task = $form->getData();

            // ... perform some action, such as saving the task to the database

            return $this->redirectToRoute('task_success');
        }

        return $this->renderForm('task/new.html.twig', [
            'form' => $form,
        ]);
    }
}

This controller follows a common pattern for handling forms and has three possible paths:

  1. When initially loading the page in a browser, the form hasn't been submitted yet and $form->isSubmitted() returns false. So, the form is created and rendered;
  2. When the user submits the form, handleRequest() recognizes this and immediately writes the submitted data back into the task and dueDate properties of the $task object. Then this object is validated (validation is explained in the next section). If it is invalid, isValid() returns false and the form is rendered again, but now with validation errors;
  3. When the user submits the form with valid data, the submitted data is again written into the form, but this time isValid() returns true. Now you have the opportunity to perform some actions using the $task object (e.g. persisting it to the database) before redirecting the user to some other page (e.g. a "thank you" or "success" page);

Note

Redirecting a user after a successful form submission is a best practice that prevents the user from being able to hit the "Refresh" button of their browser and re-post the data.

See also

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

Validating Forms

In the previous section, you learned how a form can be submitted with valid or invalid data. In Symfony, the question isn't whether the "form" is valid, but whether or not the underlying object ($task in this example) is valid after the form has applied the submitted data to it. Calling $form->isValid() is a shortcut that asks the $task object whether or not it has valid data.

Before using validation, add support for it in your application:

1
$ composer require symfony/validator

Validation is done by adding a set of rules, called (validation) constraints, to a class. You can add them either to the entity class or by using the constraints option of form types.

To see the first approach - adding constraints to the entity - in action, add the validation constraints, so that the task field cannot be empty, and the dueDate field cannot be empty, and must be a valid DateTime object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// src/Entity/Task.php
namespace App\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Task
{
    /**
     * @Assert\NotBlank
     */
    public $task;

    /**
     * @Assert\NotBlank
     * @Assert\Type("\DateTime")
     */
    protected $dueDate;
}

That's it! If you re-submit the form with invalid data, you'll see the corresponding errors printed out with the form.

To see the second approach - adding constraints to the form - refer to this section. Both approaches can be used together.

Form Validation Messages

5.2

The legacy_error_messages option was introduced in Symfony 5.2

The form types have default error messages that are more clear and user-friendly than the ones provided by the validation constraints. To enable these new messages set the legacy_error_messages option to false:

1
2
3
4
# config/packages/framework.yaml
framework:
    form:
        legacy_error_messages: false

Other Common Form Features

Passing Options to Forms

If you create forms in classes, when building the form in the controller you can pass custom options to it as the third optional argument of createForm():

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// src/Controller/TaskController.php
namespace App\Controller;

use App\Form\Type\TaskType;
// ...

class TaskController extends AbstractController
{
    public function new(): Response
    {
        $task = new Task();
        // use some PHP logic to decide if this form field is required or not
        $dueDateIsRequired = ...;

        $form = $this->createForm(TaskType::class, $task, [
            'require_due_date' => $dueDateIsRequired,
        ]);

        // ...
    }
}

If you try to use the form now, you'll see an error message: The option "require_due_date" does not exist. That's because forms must declare all the options they accept using the configureOptions() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// src/Form/Type/TaskType.php
namespace App\Form\Type;

use Symfony\Component\OptionsResolver\OptionsResolver;
// ...

class TaskType extends AbstractType
{
    // ...

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            // ...,
            'require_due_date' => false,
        ]);

        // you can also define the allowed types, allowed values and
        // any other feature supported by the OptionsResolver component
        $resolver->setAllowedTypes('require_due_date', 'bool');
    }
}

Now you can use this new form option inside the buildForm() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// src/Form/Type/TaskType.php
namespace App\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\FormBuilderInterface;

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // ...
            ->add('dueDate', DateType::class, [
                'required' => $options['require_due_date'],
            ])
        ;
    }

    // ...
}

Form Type Options

Each form type has a number of options to configure it, as explained in the Symfony form types reference. Two commonly used options are required and label.

The required Option

The most common option is the required option, which can be applied to any field. By default, this option is set to true, meaning that HTML5-ready browsers will require you to fill in all fields before submitting the form.

If you don't want this behavior, either disable client-side validation for the entire form or set the required option to false on one or more fields:

1
2
3
->add('dueDate', DateType::class, [
    'required' => false,
])

The required option does not perform any server-side validation. If a user submits a blank value for the field (either with an old browser or a web service, for example), it will be accepted as a valid value unless you also use Symfony's NotBlank or NotNull validation constraints.

The label Option

By default, the label of form fields are the humanized version of the property name (user -> User; postalAddress -> Postal Address). Set the label option on fields to define their labels explicitly:

1
2
3
4
->add('dueDate', DateType::class, [
    // set it to FALSE to not display the label for this field
    'label' => 'To Be Completed Before',
])

Tip

By default, <label> tags of required fields are rendered with a required CSS class, so you can display an asterisk by applying a CSS style:

1
2
3
label.required:before {
    content: "*";
}

Changing the Action and HTTP Method

By default, the <form> tag is rendered with a method="post" attribute, and no action attribute. This means that the form is submitted via an HTTP POST request to the same URL under which it was rendered. When building the form, use the setAction() and setMethod() methods to change this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// 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\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class TaskController extends AbstractController
{
    public function new(): Response
    {
        // ...

        $form = $this->createFormBuilder($task)
            ->setAction($this->generateUrl('target_route'))
            ->setMethod('GET')
            // ...
            ->getForm();

        // ...
    }
}

When building the form in a class, pass the action and method as form options:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// src/Controller/TaskController.php
namespace App\Controller;

use App\Form\TaskType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
// ...

class TaskController extends AbstractController
{
    public function new(): Response
    {
        // ...

        $form = $this->createForm(TaskType::class, $task, [
            'action' => $this->generateUrl('target_route'),
            'method' => 'GET',
        ]);

        // ...
    }
}

Finally, you can override the action and method in the template by passing them to the form() or the form_start() helper functions:

1
2
{# templates/task/new.html.twig #}
{{ form_start(form, {'action': path('target_route'), 'method': 'GET'}) }}

Note

If the form's method is not GET or POST, but PUT, PATCH or DELETE, Symfony will insert a hidden field with the name _method that stores this method. The form will be submitted in a normal POST request, but Symfony's routing is capable of detecting the _method parameter and will interpret it as a PUT, PATCH or DELETE request. The http_method_override option must be enabled for this to work.

Changing the Form Name

If you inspect the HTML contents of the rendered form, you'll see that the <form> name and the field names are generated from the type class name (e.g. <form name="task" ...> and <select name="task[dueDate][date][month]" ...>).

If you want to modify this, use the createNamed() method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// src/Controller/TaskController.php
namespace App\Controller;

use App\Form\TaskType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormFactoryInterface;
// ...

class TaskController extends AbstractController
{
    public function new(FormFactoryInterface $formFactory): Response
    {
        $task = ...;
        $form = $formFactory->createNamed('my_name', TaskType::class, $task);

        // ...
    }
}

You can even suppress the name completely by setting it to an empty string.

Client-Side HTML Validation

Thanks to HTML5, many browsers can natively enforce certain validation constraints on the client side. The most common validation is activated by adding a required attribute on fields that are required. For browsers that support HTML5, this will result in a native browser message being displayed if the user tries to submit the form with that field blank.

Generated forms take full advantage of this new feature by adding sensible HTML attributes that trigger the validation. The client-side validation, however, can be disabled by adding the novalidate attribute to the <form> tag or formnovalidate to the submit tag. This is especially useful when you want to test your server-side validation constraints, but are being prevented by your browser from, for example, submitting blank fields.

1
2
3
4
{# templates/task/new.html.twig #}
{{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }}
    {{ form_widget(form) }}
{{ form_end(form) }}

Form Type Guessing

If the object handled by the form includes validation constraints, Symfony can introspect that metadata to guess the type of your field. In the above example, Symfony can guess from the validation rules that the task field is a normal TextType field and the dueDate field is a DateType field.

To enable Symfony's "guessing mechanism", omit the second argument to the add() method, or pass null to it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// src/Form/Type/TaskType.php
namespace App\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\DateType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            // if you don't define field options, you can omit the second argument
            ->add('task')
            // if you define field options, pass NULL as second argument
            ->add('dueDate', null, ['required' => false])
            ->add('save', SubmitType::class)
        ;
    }
}

Caution

When using a specific form validation group, the field type guesser will still consider all validation constraints when guessing your field types (including constraints that are not part of the validation group(s) being used).

Form Type Options Guessing

When the guessing mechanism is enabled for some field, in addition to its form type, the following options will be guessed too:

required
The required option is guessed based on the validation rules (i.e. is the field NotBlank or NotNull) or the Doctrine metadata (i.e. is the field nullable). This is very useful, as your client-side validation will automatically match your validation rules.
maxlength
If the field is some sort of text field, then the maxlength option attribute is guessed from the validation constraints (if Length or Range is used) or from the Doctrine metadata (via the field's length).

If you'd like to change one of the guessed values, override it in the options field array:

1
->add('task', null, ['attr' => ['maxlength' => 4]])

See also

Besides guessing the form type, Symfony also guesses validation constraints if you're using a Doctrine entity. Read Databases and the Doctrine ORM guide for more information.

Unmapped Fields

When editing an object via a form, all form fields are considered properties of the object. Any fields on the form that do not exist on the object will cause an exception to be thrown.

If you need extra fields in the form that won't be stored in the object (for example to add an "I agree with these terms" checkbox), set the mapped option to false in those fields:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// ...
use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
use Symfony\Component\Form\Extension\Core\Type\SubmitType;
use Symfony\Component\Form\FormBuilderInterface;

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('task')
            ->add('dueDate')
            ->add('agreeTerms', CheckboxType::class, ['mapped' => false])
            ->add('save', SubmitType::class)
        ;
    }
}

These "unmapped fields" can be set and accessed in a controller with:

1
2
$form->get('agreeTerms')->getData();
$form->get('agreeTerms')->setData(true);

Additionally, if there are any fields on the form that aren't included in the submitted data, those fields will be explicitly set to null.

Learn more

When building forms, keep in mind that the first goal of a form is to translate data from an object (Task) to an HTML form so that the user can modify that data. The second goal of a form is to take the data submitted by the user and to re-apply it to the object.

There's a lot more to learn and a lot of powerful tricks in the Symfony forms:

Reference:

Advanced Features:

Form Themes and Customization:

Events:

Validation:

Misc.:

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version