single: Forms
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.
In applications using Symfony Flex <symfony-flex>
, run this command to install the form feature before using it:
$ composer require symfony/form
The recommended workflow when working with Symfony forms is the following:
- Build the form in a Symfony controller or using a dedicated form class;
- Render the form in a template so the user can edit and submit it;
- 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 simple Todo list application that displays "tasks".
Users create and edit tasks using Symfony forms. Each task is an instance of the following Task
class:
// src/Entity/Task.php
namespace App\Entity;
class Task
{
protected $task;
protected $dueDate;
public function getTask()
{
return $this->task;
}
public function setTask($task)
{
$this->task = $task;
}
public function getDueDate()
{
return $this->dueDate;
}
public function setDueDate(\DateTime $dueDate = null)
{
$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 </doctrine>
in the same way.
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 </reference/forms/types>
and you can also create your own form types </form/create_custom_field_type>
.
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.
If your controller extends from the AbstractController <the-base-controller-class-services>
, use the createFormBuilder()
helper:
// 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;
class TaskController extends AbstractController
{
public function new(Request $request)
{
// 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 <controller-accessing-services>
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 <form-types>
(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.
Symfony recommends to put 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 <form-types>
that implement Symfony\\Component\\Form\\FormTypeInterface
. However, it's better to extend from Symfony\\Component\\Form\\AbstractType
, which already implements the interface and provides some utilities:
// 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)
{
$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 <the-base-controller-class-services>
, use the createForm()
helper (otherwise, use the create()
method of the form.factory
service):
// src/Controller/TaskController.php
namespace App\Controller;
use App\Form\Type\TaskType;
// ...
class TaskController extends AbstractController
{
public function new()
{
// 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 </form/embedded>
, 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:
// 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)
{
$resolver->setDefaults([
'data_class' => Task::class,
]);
}
}
Now that the form has been created, the next step is to render it. Instead of passing the entire form object to the template, use the createView()
method to build another object with the visual representation of the form:
// 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;
class TaskController extends AbstractController
{
public function new(Request $request)
{
$task = new Task();
// ...
$form = $this->createForm(TaskType::class, $task);
return $this->render('task/new.html.twig', [
'form' => $form->createView(),
]);
}
}
Then, use some form helper functions <reference-form-twig-functions>
to render the form contents:
{# templates/task/new.html.twig #}
{{ form(form) }}
That's it! The form() function <reference-forms-twig-form>
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 <forms-change-action-method>
.
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 4 integration with Symfony forms </form/bootstrap4>
you can set this option to generate forms compatible with the Bootstrap 4 CSS framework:
# config/packages/twig.yaml
twig:
form_themes: ['bootstrap_4_layout.html.twig']
<!-- config/packages/twig.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:twig="http://symfony.com/schema/dic/twig"
xsi:schemaLocation="http://symfony.com/schema/dic/services
https://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/twig
https://symfony.com/schema/dic/twig/twig-1.0.xsd">
<twig:config>
<twig:form-theme>bootstrap_4_layout.html.twig</twig:form-theme>
<!-- ... -->
</twig:config>
</container>
// config/packages/twig.php
$container->loadFromExtension('twig', [
'form_themes' => [
'bootstrap_4_layout.html.twig',
],
// ...
]);
The built-in Symfony form themes <symfony-builtin-forms>
include Bootstrap 3 and 4 and Foundation 5. You can also create your own Symfony form theme <create-your-own-form-theme>
.
In addition to form themes, Symfony allows you to customize the way fields are rendered </form/form_customization>
with multiple functions to render each field part separately (widgets, labels, errors, help messages, etc.)
The recommended way of processing forms <best-practice-handle-form>
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:
// ...
use Symfony\Component\HttpFoundation\Request;
public function new(Request $request)
{
// just setup 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
// for example, if Task is a Doctrine entity, save it!
// $entityManager = $this->getDoctrine()->getManager();
// $entityManager->persist($task);
// $entityManager->flush();
return $this->redirectToRoute('task_success');
}
return $this->render('task/new.html.twig', [
'form' => $form->createView(),
]);
}
This controller follows a common pattern for handling forms and has three possible paths:
- When initially loading the page in a browser, the form hasn't been submitted yet and
$form->isSubmitted()
returnsfalse
. So, the form is created and rendered; - When the user submits the form,
Symfony\\Component\\Form\\FormInterface::handleRequest
recognizes this and immediately writes the submitted data back into thetask
anddueDate
properties of the$task
object. Then this object is validated (validation is explained in the next section). If it is invalid,Symfony\\Component\\Form\\FormInterface::isValid
returnsfalse
and the form is rendered again, but now with validation errors; - When the user submits the form with valid data, the submitted data is again written into the form, but this time
Symfony\\Component\\Form\\FormInterface::isValid
returnstrue
. 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.
Caution
The createView()
method should be called after handleRequest()
is called. Otherwise, when using form events </form/events>
, changes done in the *_SUBMIT
events won't be applied to the view (like validation errors).
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 </form/direct_submit>
.
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:
$ composer require symfony/validator
Validation is done by adding a set of rules (called constraints) to a class. To see this in action, add validation constraints so that the task
field cannot be empty and the dueDate
field cannot be empty and must be a valid DateTime object.
// 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;
}
# config/validator/validation.yaml
App\Entity\Task:
properties:
task:
- NotBlank: ~
dueDate:
- NotBlank: ~
- Type: \DateTime
<!-- config/validator/validation.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping
https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
<class name="App\Entity\Task">
<property name="task">
<constraint name="NotBlank"/>
</property>
<property name="dueDate">
<constraint name="NotBlank"/>
<constraint name="Type">\DateTime</constraint>
</property>
</class>
</constraint-mapping>
// src/Entity/Task.php
namespace App\Entity;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Type;
use Symfony\Component\Validator\Mapping\ClassMetadata;
class Task
{
// ...
public static function loadValidatorMetadata(ClassMetadata $metadata)
{
$metadata->addPropertyConstraint('task', new NotBlank());
$metadata->addPropertyConstraint('dueDate', new NotBlank());
$metadata->addPropertyConstraint(
'dueDate',
new Type(\DateTime::class)
);
}
}
That's it! If you re-submit the form with invalid data, you'll see the corresponding errors printed out with the form. Read the Symfony validation documentation </validation>
to learn more about this powerful feature.
If you create forms in classes <creating-forms-in-classes>
, when building the form in the controller you can pass custom options to it as the third optional argument of createForm()
:
// src/Controller/TaskController.php
namespace App\Controller;
use App\Form\Type\TaskType;
// ...
class TaskController extends AbstractController
{
public function new()
{
$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:
// src/Form/Type/TaskType.php
namespace App\Form\Type;
use Symfony\Component\OptionsResolver\OptionsResolver;
// ...
class TaskType extends AbstractType
{
// ...
public function configureOptions(OptionsResolver $resolver)
{
$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:
// 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)
{
$builder
// ...
->add('dueDate', DateType::class, [
'required' => $options['require_due_date'],
])
;
}
// ...
}
Each form type <form-types>
has a number of options to configure it, as explained in the Symfony form types reference </reference/forms/types>
. Two commonly used options are required
and label
.
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 to fill in all fields before submitting the form.
If you don't want this behavior, either disable client-side validation <forms-html5-validation-disable>
for the entire form or set the required
option to false
on one or more fields:
->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.
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:
->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 for required fields applying these CSS styles:
label.required:before {
content: "*";
}
By default, a form will be submitted via an HTTP POST request to the same URL under which the form was rendered. When building the form in the controller, use the setAction()
and setMethod()
methods to change this:
// 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()
{
// ...
$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:
// src/Controller/TaskController.php
namespace App\Controller;
use App\Form\TaskType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
class TaskController extends AbstractController
{
public function new()
{
// ...
$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:
{# 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 </routing>
is capable of detecting the _method
parameter and will interpret it as a PUT
, PATCH
or DELETE
request. See the configuration-framework-http_method_override
option.
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 Symfony\\Component\\Form\\FormFactoryInterface::createNamed
method:
// src/Controller/TaskController.php
namespace App\Controller;
use App\Form\TaskType;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
class TaskController extends AbstractController
{
public function new()
{
$task = ...;
$form = $this->get('form.factory')->createNamed('my_name', TaskType::class, $task);
// ...
}
}
You can even suppress the name completely by setting it to an empty string.
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.
{# templates/task/new.html.twig #}
{{ form_start(form, {'attr': {'novalidate': 'novalidate'}}) }}
{{ form_widget(form) }}
{{ form_end(form) }}
If the object handled by the form includes validation constraints, Symfony can introspect that metadata to guess the type of your field and set it up for you. In the above example, Symfony can guess from the validation rules that both the task
field is a normal TextType
field and the dueDate
field is a DateType
field.
When building the form, omit the second argument to the add()
method, or pass null
to it, to enable Symfony's "guessing mechanism":
// 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)
{
$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 </form/validation_groups>
, 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).
When the guessing mechanism is enabled for some field (i.e. you omit or pass null
as the second argument to add()
), in addition to its form type, the following options can be guessed too:
required
The
required
option can be guessed based on the validation rules (i.e. is the fieldNotBlank
orNotNull
) or the Doctrine metadata (i.e. is the fieldnullable
). 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 can be guessed from the validation constraints (ifLength
orRange
is used) or from theDoctrine </doctrine>
metadata (via the field's length).
If you'd like to change one of the guessed values, override it by passing the option in the options field array:
->add('task', null, ['attr' => ['maxlength' => 4]])
Besides guessing the form type, Symfony also guesses validation constraints <validating-forms>
if you're using a Doctrine entity. Read automatic_object_validation
guide for more information.
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:
use Symfony\Component\Form\FormBuilderInterface;
public function buildForm(FormBuilderInterface $builder, array $options)
{
$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:
$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
.
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:
/reference/forms/types
Advanced Features:
/controller/upload_file /security/csrf /form/form_dependencies /form/create_custom_field_type /form/data_transformers /form/data_mappers /form/create_form_type_extension /form/type_guesser
Form Themes and Customization:
/form/bootstrap4 /form/form_customization /form/form_themes
Events:
/form/events /form/dynamic_form_modification
Validation:
/form/validation_groups /form/validation_group_service_resolver /form/button_based_validation /form/disabling_validation
Misc.:
/form/direct_submit /form/embedded /form/form_collections /form/inherit_data_option /form/multiple_buttons /form/unit_testing /form/use_empty_data /form/without_class