From 6aa81d1d366250fc38b15aedd158843ce8dc68fa Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 14 Dec 2016 00:10:39 +0100 Subject: [PATCH 1/9] Include example of a cascaded "persist" operation Following up on https://github.com/doctrine/doctrine2/issues/2943 I started to clarify how it's supposed to be done. Please check if this would be necessary (at line 511): `$myFirstComment->setUser($user);` ...and add it (in case). --- docs/en/reference/working-with-associations.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 85ffaee3a..f79371d16 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -453,11 +453,11 @@ following code: $user->addComment($myFirstComment); $em->persist($user); - $em->persist($myFirstComment); + $em->persist($myFirstComment); // mandatory if `persist` isn't set $em->flush(); Even if you *persist* a new User that contains our new Comment this -code would fail if you removed the call to +code requires the explicit call to ``EntityManager#persist($myFirstComment)``. Doctrine 2 does not cascade the persist operation to all nested entities that are new as well. @@ -500,6 +500,18 @@ and the "remove" operation. //... } +Now you can persist the `User` entity like that: + +.. code-block:: php + + addComment($myFirstComment); + + $em->persist($user); + $em->flush(); + Even though automatic cascading is convenient it should be used with care. Do not blindly apply cascade=all to all associations as it will unnecessarily degrade the performance of your application. From a06f8d475992f8fe4ac7cd0e6463882ed2f7c25f Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 14 Dec 2016 21:38:10 +0100 Subject: [PATCH 2/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index f79371d16..32fcfdaba 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -453,7 +453,7 @@ following code: $user->addComment($myFirstComment); $em->persist($user); - $em->persist($myFirstComment); // mandatory if `persist` isn't set + $em->persist($myFirstComment); // mandatory if `cascade: persist` isn't set $em->flush(); Even if you *persist* a new User that contains our new Comment this From 29062fb42e7dd31874f74a1ceb1fd686c290b6ad Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 14 Dec 2016 21:39:47 +0100 Subject: [PATCH 3/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 32fcfdaba..2ef52f781 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -457,7 +457,7 @@ following code: $em->flush(); Even if you *persist* a new User that contains our new Comment this -code requires the explicit call to +code requires an explicit call to ``EntityManager#persist($myFirstComment)``. Doctrine 2 does not cascade the persist operation to all nested entities that are new as well. From 879d4e7df063745f534115aedc8ac35f7139c37e Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Wed, 14 Dec 2016 21:46:18 +0100 Subject: [PATCH 4/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 2ef52f781..7e088f944 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -500,7 +500,8 @@ and the "remove" operation. //... } -Now you can persist the `User` entity like that: +Since ``cascade: persist`` is configured for the ``User#commentsAuthored`` +association, you can now create a user and persist his comment as follows: .. code-block:: php From 1a8eeacfba8cb2d1a1ce9b24f91398b525089c55 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Sun, 18 Dec 2016 21:42:08 +0100 Subject: [PATCH 5/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 7e088f944..0768c3ede 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -453,7 +453,7 @@ following code: $user->addComment($myFirstComment); $em->persist($user); - $em->persist($myFirstComment); // mandatory if `cascade: persist` isn't set + $em->persist($myFirstComment); // required, if `cascade: persist` isn't set $em->flush(); Even if you *persist* a new User that contains our new Comment this From a8a3a8c9e7796e8984ff76e31a7f48adb5357a63 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Sun, 18 Dec 2016 21:58:44 +0100 Subject: [PATCH 6/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 0768c3ede..106da34ec 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -513,8 +513,14 @@ association, you can now create a user and persist his comment as follows: $em->persist($user); $em->flush(); -Even though automatic cascading is convenient it should be used -with care. Do not blindly apply cascade=all to all associations as +.. note:: + + This code does not associate the newly created comment with the user. + To achieve this, you *always* have to call ``$myFirstComment->setUser($user);`` – + no matter if ``cascade: persist`` is set or not. + +Even though automatic cascading is convenient, it should be used +with care. Do not blindly apply ``cascade=all`` to all associations as it will unnecessarily degrade the performance of your application. For each cascade operation that gets activated Doctrine also applies that operation to the association, be it single or From eecf4382b03d720b56a6a9bc4cce799c190cde40 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Sun, 18 Dec 2016 23:05:10 +0100 Subject: [PATCH 7/9] Update working-with-associations.rst --- docs/en/reference/working-with-associations.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 106da34ec..21f1fa356 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -442,7 +442,7 @@ The following cascade options exist: The following example is an extension to the User-Comment example of this chapter. Suppose in our application a user is created -whenever he writes his first comment. In this case we would use the +whenever they write their first comment. In this case we would use the following code: .. code-block:: php @@ -462,7 +462,7 @@ code requires an explicit call to cascade the persist operation to all nested entities that are new as well. -More complicated is the deletion of all of a user's comments when he is +More complicated is the deletion of all user's comments when the user is removed from the system: .. code-block:: php @@ -501,7 +501,7 @@ and the "remove" operation. } Since ``cascade: persist`` is configured for the ``User#commentsAuthored`` -association, you can now create a user and persist his comment as follows: +association, you can now create a user and persist their comments as follows: .. code-block:: php From f3909ae88527aa254970b63f30f68272c1e1cbdb Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Fri, 23 Dec 2016 20:09:25 +0100 Subject: [PATCH 8/9] Update working-with-associations.rst --- .../reference/working-with-associations.rst | 24 ++++--------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index 21f1fa356..d1d7b4265 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -405,25 +405,11 @@ There are two approaches to handle this problem in your code: Transitive persistence / Cascade Operations ------------------------------------------- -Persisting, removing, detaching, refreshing and merging individual entities can -become pretty cumbersome, especially when a highly interweaved object graph -is involved. Therefore Doctrine 2 provides a -mechanism for transitive persistence through cascading of these -operations. Each association to another entity or a collection of -entities can be configured to automatically cascade certain -operations. By default, no operations are cascaded. - -The following cascade options exist: - - -- persist : Cascades persist operations to the associated - entities. -- remove : Cascades remove operations to the associated entities. -- merge : Cascades merge operations to the associated entities. -- detach : Cascades detach operations to the associated entities. -- refresh : Cascades refresh operations to the associated entities. -- all : Cascades persist, remove, merge, refresh and detach operations to - associated entities. +When working with many associated entities, you sometimes don't want to "expose" all entities to your PHP application. +Therefore Doctrine 2 provides a mechanism for transitive persistence through cascading of certain operations. +Each association to another entity or a collection of +entities can be configured to automatically cascade the following operations to the associated entities: +``persist``, ``remove``, ``merge``, ``detach``, ``refresh`` or ``all``. .. note:: From 7c168c20474b48eb724d019cba70dd0ee783c6bd Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 9 Jan 2017 14:07:17 +0100 Subject: [PATCH 9/9] Update working-with-associations.rst As requested: https://github.com/doctrine/doctrine2/pull/6171#pullrequestreview-15695400 --- docs/en/reference/working-with-associations.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/reference/working-with-associations.rst b/docs/en/reference/working-with-associations.rst index d1d7b4265..e3a148913 100644 --- a/docs/en/reference/working-with-associations.rst +++ b/docs/en/reference/working-with-associations.rst @@ -495,6 +495,7 @@ association, you can now create a user and persist their comments as follows: $user = new User(); $myFirstComment = new Comment(); $user->addComment($myFirstComment); + $myFirstComment->setUser($user); $em->persist($user); $em->flush();