From 6aa81d1d366250fc38b15aedd158843ce8dc68fa Mon Sep 17 00:00:00 2001
From: Thomas Landauer <thomas@landauer.at>
Date: Wed, 14 Dec 2016 00:10:39 +0100
Subject: [PATCH] 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
+
+    <?php
+    $user = new User();
+    $myFirstComment = new Comment();
+    $user->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.