[Form] Document usage of adders and removers

[webmozart]

As of symfony/symfony#3239 the "collection" and "choice" types (with multiple=true) as well as subtypes (such as "entity") will try to discover an adder and a remover method in your model if "by_reference" is set to false.

Example form:

$form = $this->createFormBuilder($article)
    ->add('tags', null, array('by_reference' => false))
    ->getForm();

The underlying article class is expected to look like this:

class Article
{
    public function addTag($tag) { ... }
    public function removeTag($tag) { ... }
    public function getTags($tag) { ... }
}

If adder and remover are not found, the form behaves differently depending on whether getTags returns an object or an array.

1. If it returns an object (collection), the object is modified by reference and not written back
2. If it returns an array, the array is modified and written back using setTags

You can force a write-back in case (1) by setting the field option "by_reference" to false. Note that in this case, adders and removers won't be used even if present! Instead, the expected object signature is

class Article
{
    public function setTags($tags) { ... }
    public function getTags($tag) { ... }
}

[keymaster]

Also, the adder/remover prefixes are configurable.
symfony/symfony@9b0245b

[webmozart]

@keymaster This has changed again. See #1227

[wouterj]

This should get changed in cookbook/form/form_collections

[weaverryan]

@wouterj I agree that we should add the addXxx and removeXxx details as needed to the form_collections chapter. We then might also consider a short, standalone cookbook article with an expanded version of what we have here. The advantage is that it helps keep form_collections short while letting us talk about this in good detail. We can also link to it from other places.

[wouterj]

Closing this as #2434 is merged