Symfony Forms Cookbook

Basic form building

Build a form object and render it in a template from within a controller:

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use AppBundle\Entity\Task;
use Symfony\Component\HttpFoundation\Request;

class DefaultController extends Controller
{
    public function newAction(Request $request)
    {
        // create a task and give it some dummy data for this example
        $task = new Task();
        $task->setTask('Write a blog post');
        $task->setDueDate(new \DateTime('tomorrow'));

        $form = $this->createFormBuilder($task)
            ->add('task', 'text')
            ->add('dueDate', 'date')
            ->add('save', 'submit', array('label' => 'Create Task'))
            ->getForm();

        return $this->render('Default/new.html.twig', array(
            'form' => $form->createView(),
        ));
    }
}

Render a form

After passing a form "view" object to a Twig template, the form can be rendered with form helper functions:

{# app/Resources/views/Default/new.html.twig #}
{{ form_start(form) }}
{{ form_errors(form) }}
{{ form_widget(form) }}
{{ form_end(form) }}

form_end(form) renders the form's end tag along with hidden fields, including CSRF protection. It also renders any fields that have not already been rendered.

Rendering form fields

• form_row(form.property) renders a form input along with a label and error messages specific to the form field. form is the name of the form variable, and property is the name of the property being rendered, e.g. form.id, form.name, etc.
• The components wrapped up in form_row() can be rendered separately:
  • form_label(form.property) renders just the label for the field.
    • Override the label text with form_label(form.property, 'Custom Label Text')
  • form_errors(form.property) renders errors for the field.
  • form_widget(form.property) renders the form input.
    • Set properties for the input with form_widget(form.property, {attr: {'class': 'my-custom-class'}})
• Individual properties of the fields can be accessed with
  • form.entity.property.id
  • form.entity.property.name
  • form.entity.property.label
  • ^^ Actually I'm not 100% sure that's how it works. Try it out to confirm.

Handling form submissions

In the controller, the form object translates user data submitted with the form.

public function newAction(Request $request)
{
    // just setup a fresh $task object (remove the dummy data)
    $task = new Task();

    $form = $this->createFormBuilder($task)
        ->add('task', 'text')
        ->add('dueDate', 'date')
        ->add('save', 'submit', array('label' => 'Create Task'))
        ->getForm();

    $form->handleRequest($request);

    if ($form->isValid()) {

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

        return $this->redirect($this->generateUrl('task_success'));
    }

    // ...
}

1. When the page is first loaded, the form is created and rendered.
   1. handleRequest() recognizes that the form was not submitted and does nothing.
   2. isValid() returns false if the form was not submitted.
2. When the form is submitted, handleRequest() translates the data
   1. handleRequest() updates the corresponding properties of the entity object ($task in this case) with the form data.
   2. isValid() returns false if the form data isn't valid.
      1. Execution skips that block where the data would be processed, and instead goes to the original view, which is rendered with the submitted form data and error messages.

Multiple submit buttons

Add the buttons to the form builder in the controller:

$form = $this->createFormBuilder($task)
    ->add('task', 'text')
    ->add('dueDate', 'date')
    ->add('save', 'submit', array('label' => 'Create Task'))
    ->add('saveAndAdd', 'submit', array('label' => 'Save and Add'))
    ->getForm();

Test which button was clicked in the controller using the button's isClicked() method:

if ($form->isValid()) {
    // ... perform some action, such as saving the task to the database

    $nextAction = $form->get('saveAndAdd')->isClicked()
        ? 'task_new'
        : 'task_success';

    return $this->redirect($this->generateUrl($nextAction));
}

Form validation

With Symfony, it isn't the form that is validated, rather it is the entity object that is tested to confirm that it contains valid data. This is does by defining a set of rules, or constraints, for the entity class.

# AppBundle/Resources/config/validation.yml
AppBundle\Entity\Task:
    properties:
        task:
            - NotBlank: ~
        dueDate:
            - NotBlank: ~
            - Type: \DateTime

The above configuration specifies that the task field cannot be empty and the dueDate field cannot be empty and must be a valid DateTime object.

Validation groups

Different groups can be defined to validate the underlying object, either in the controller:

$form = $this->createFormBuilder($users, array(
    'validation_groups' => array('registration'),
))->add(...);

Or in a form class:

use Symfony\Component\OptionsResolver\OptionsResolverInterface;

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => array('registration'),
    ));
}

Disabling validation

Set the validation_groups option to false:

public function setDefaultOptions(OptionsResolverInterface $resolver)
{
    $resolver->setDefaults(array(
        'validation_groups' => false,
    ));
}

Forms without classes

Example of how to set this up in a controller:

// make sure you've imported the Request namespace above the class
use Symfony\Component\HttpFoundation\Request;
// ...

public function contactAction(Request $request)
{
    $defaultData = array('message' => 'Type your message here');
    $form = $this->createFormBuilder($defaultData)
        ->add('name', 'text')
        ->add('email', 'email')
        ->add('message', 'textarea')
        ->add('send', 'submit')
        ->getForm();

    $form->handleRequest($request);

    if ($form->isValid()) {
        // data is an array with "name", "email", and "message" keys
        $data = $form->getData();
    }

    // ... render the form
}

Multiple checkboxes without an entity class

Goal: To display a list of records, select the records with checkboxes, then apply a batch update to the records when the form is submitted.

Controller

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

//...
	/**
	 * @Route("/pending", name="_pending")
	 */
	public function pendingAction(Request $request)
	{
		// retrieve pending tutorials from database
		$groups = $this->getDoctrine()
			->getRepository('AppBundle:TutorialGroupTemp')
			->findAll();
		$tutorial_data = array();
		foreach($groups as $group) {
			$group->getTutorials();
			foreach ($group->tutorials as $tutorial) {
				$tutorial_data[$tutorial->getId()] = $tutorial->getName();
			}
		}

		// define form inputs
		$fb = $this->createFormBuilder();
		foreach($tutorial_data as $key => $label) {
			$fb->add('tutorialID', 'choice', array(
				'label' => 'Tutorials',
				'multiple' => true,
				'expanded' => true,
				'choices' => $tutorial_data,
				'required' => false
			));
		}
		$fb->add('update', 'submit', array('label' => 'save selected'));
		$form = $fb->getForm();
		
		// process form submission
		$form->handleRequest($request);
		
		if ($form->isValid()) {
			
			// collect form data
			$data = $form->getData();
			
			/** @todo process form data */
		}

		// display listings view		
		return $this->render("tutorials/pending.html.twig", array(
			'groups' => $groups,
			'form' => $form->createView()
		));
	}
// ...

1. Store all the record values in an array to be assigned to the checkbox inputs elements.
2. Use a form builder object to define the form.
   1. Call the add() method for each checkbox to be added the form.
      1. Checkboxes representing an array of choices are created using choice as the form element
      2. The options 'multiple=true' and 'expanded=true' are what make it render as checkboxes as opposed to dropdowns.
      3. The values of the checkboxes are passed to the form builder with the choices option.
   2. In this case submit buttons are repeated throughout the form for the convenience of not having to scroll through all the listings to find them.
      1. The form_widget() twig routine will only render an input once because generally they are all assigned id attributes.
      2. The submit button must still be added to the form builder in order to validate the form data.
3. The form data is collected and processed with the handleRequest() and getData() calls. (getData() wouldn't be used if the form data was being assigned to an entity class.)
4. The form is validated with the isValid() call. If form data is not being submitted, this block is quietly skipped over.
5. It's necessary to pass the form view to the template when rendering the view.

N.B. There are probably other things that I could do (form class? services?) that would be better practices. As documented here it works. Update with any new practices.