-
-
Notifications
You must be signed in to change notification settings - Fork 5.1k
/
by_reference.rst.inc
45 lines (34 loc) · 1.62 KB
/
by_reference.rst.inc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
by_reference
~~~~~~~~~~~~
**type**: ``Boolean`` **default**: ``true``
In most cases, if you have a ``name`` field, then you expect ``setName()``
to be called on the underlying object. In some cases, however, ``setName()``
may *not* be called. Setting ``by_reference`` ensures that the setter is
called in all cases.
To explain this further, here's a simple example::
$builder = $this->createFormBuilder($article);
$builder
->add('title', 'text')
->add(
$builder->create('author', 'form', array('by_reference' => ?))
->add('name', 'text')
->add('email', 'email')
)
If ``by_reference`` is true, the following takes place behind the scenes
when you call ``submit()`` (or ``handleRequest()``) on the form::
$article->setTitle('...');
$article->getAuthor()->setName('...');
$article->getAuthor()->setEmail('...');
Notice that ``setAuthor()`` is not called. The author is modified by reference.
If you set ``by_reference`` to false, submitting looks like this::
$article->setTitle('...');
$author = $article->getAuthor();
$author->setName('...');
$author->setEmail('...');
$article->setAuthor($author);
So, all that ``by_reference=false`` really does is force the framework to
call the setter on the parent object.
Similarly, if you're using the :doc:`collection</reference/forms/types/collection>`
form type where your underlying collection data is an object (like with Doctrine's
``ArrayCollection``), then ``by_reference`` must be set to ``false`` if you
need the adder and remover (e.g. ``addAuthor()`` and ``removeAuthor()``) to be called.