A form that does not map to the data of its parent should either be
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()
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()
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).
@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?
@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:
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?
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: http://symfony.com/doc/2.1/cookbook/form/use_virtuals_forms.html
Does this mean only tthe unmapped option needs to be documented or should the documentation be extended somewhere to also mention the virtual option?
Both of the options aren't documented yet on the form reference, that's something that needs to be done. See also #2362