Adding help notes for the EntityManager::clear() method

Author: javiereguiluz

tests/AppBundle/Controller/BlogControllerTest.php

@@ -85,11 +85,18 @@ public function testNewComment()
 
         $this->assertSame(Response::HTTP_FOUND, $client->getResponse()->getStatusCode());
 
+        // in order to improve performance, Doctrine doesn't make database calls to
+        // get the objects already present in memory. This means that this test will fail
+        // because new comments are added at the end of the list of comments and the
+        // "@ORM\OrderBy()" defined in the Post entity won't be respected. The solution
+        // is to call the clear() method on the Entity Manager, which removes the in-memory
+        // changes and forces loading objects from the database again.
         $client->getContainer()->get('doctrine')->getManager()->clear();
 
-        $post = $client->getContainer()->get('doctrine')->getRepository(Post::class)->find(1);
         // The first one is the most recent comment because of the automatic sorting
-        // defined in the comments association of the Post entity
+        // defined in the comments association of the Post entity. This test can only
+        // work when using the clear() method as explained in the above comment.
+        $post = $client->getContainer()->get('doctrine')->getRepository(Post::class)->find(1);
         $comment = $post->getComments()->first();
 
         $this->assertSame($commentsCount + 1, $post->getComments()->count());