Skip to content


[Form] Document how unmapped forms can be implemented #1387

webmozart opened this Issue · 7 comments

5 participants

Symfony member

See symfony/symfony#3995

A form that does not map to the data of its parent should either be

  • unmapped ("mapped" => false)
  • virtual ("virtual" => true)

Unmapped forms are completely independent of their data. They have their own data, and children will be accessed to this data.

// Unmapped forms need to be filled with data explicitely
$form->add('address', 'form', array('mapped' => false));
// Maps to $address->getStreet()
$form->get('address')->add('street', 'text');

Virtual forms are not mapped to their parents data, but their children are.

// Virtual forms will not be mapped with data
$form->add('address', 'form', array('virtual' => true));
// Maps to $form->getData()->getStreet()
$form->get('address')->add('street', 'text');

Unmapped forms are useful if you want to embed forms that don't have a connection with the data of their parent form.

Virtual forms are useful if you use a form only in order to structure your view (see symfony/symfony#3995) or if you want to collect a set of field definitions that can be inserted ("copied") into the parent form (think traits).

Symfony member

@weaverryan this should get a missing documentation label


I found the virtual option in the 2.0 branch and the mapped option in 2.1. Correct?

If this is correct, I would start adding the virtual description to 2.0, waiting till it's merged in 2.1/2.2 and then add the mapped to 2.1. Is this the way to go?

Symfony member

@Sgoettschkes virtual still exist in 2.1, 2.2 and 2.3. It is not the same meaning than mapped


@stof I know. Maybe I described it the wrong way:

  • virtual exists since 2.0
  • mapped exists since 2.1

To make merging the document easier, I was thinking about adding the virtual option and making a PR against 2.0. If this one is merged into all branches, I would make a PR against 2.1 with the mapped option changes.

It's a workflow we use at work very often when many changes are expected against one document, to prevent merge conflicts.

If you don't think this is neccessary I don't mind doing both PR at the same time, but I still think they have to be split up as mapped was introduced in 2.1, right?

Symfony member

You're workflow is the way I recommend to use (it's the most GITish solution)


I just realized there is a whole cookbook explaining the virtual option:

Does this mean only tthe unmapped option needs to be documented or should the documentation be extended somewhere to also mention the virtual option?

Symfony member

Both of the options aren't documented yet on the form reference, that's something that needs to be done. See also #2362

@weaverryan weaverryan closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.