Add QueryBuilder vs DQL section

bocharsky-bw · bocharsky-bw · commit 011505efaab6 · 2015-08-19T23:49:01.000+03:00
Describe difference between QueryBuilder and DQL usage
diff --git a/book/doctrine.rst b/book/doctrine.rst
@@ -766,8 +766,10 @@ covered later), group, etc. For more information, see the official
 Querying for Objects Using Doctrine's Query Builder
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Instead of writing a DQL string, you can alternatively use a helpful object called
-the ``QueryBuilder`` to build that string for you::
+Instead of writing a DQL string, you can use a helpful object called the
+``QueryBuilder`` to build that string for you. This is usefull when the actual query
+depends on dynamic conditions, as your code soon becomes hard to read with
+DQL as you start to concatenate strings::
 
     $repository = $this->getDoctrine()
         ->getRepository('AppBundle:Product');
@@ -791,6 +793,14 @@ normal ``Query`` object, which can be used to get the result of the query.
 For more information on Doctrine's Query Builder, consult Doctrine's
 `Query Builder`_ documentation.
 
+DQL vs Query Builder
+~~~~~~~~~~~~~~~~~~~~
+
+When the actual query depends on dynamic conditions, your code soon becomes hard
+to read as you start to concatenate strings. In these cases, it's better to use
+the Doctrine QueryBuilder which provides a fluent interface to dynamically add
+every part of the query.
+
 .. _book-doctrine-custom-repository-classes:
 
 Custom Repository Classes
