From 6a23e6be96ad43555f077dcf22fdbc84a5c8e4bc Mon Sep 17 00:00:00 2001
From: "Fabio B. Silva" <fabio.bat.silva@gmail.com>
Date: Sun, 13 Jan 2013 15:56:11 -0200
Subject: [PATCH] =?UTF-8?q?Docs=20for=20=E2=80=9CNEW=E2=80=9D=20Operator?=
 =?UTF-8?q?=20Syntax?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 en/reference/dql-doctrine-query-language.rst | 38 ++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/en/reference/dql-doctrine-query-language.rst b/en/reference/dql-doctrine-query-language.rst
index 2ad6f5faf..a6ebe8b56 100644
--- a/en/reference/dql-doctrine-query-language.rst
+++ b/en/reference/dql-doctrine-query-language.rst
@@ -451,6 +451,44 @@ You use the partial syntax when joining as well:
     $query = $em->createQuery('SELECT partial u.{id, username}, partial a.{id, name} FROM CmsUser u JOIN u.articles a');
     $users = $query->getResult(); // array of partially loaded CmsUser objects
 
+"NEW" Operator Syntax
+^^^^^^^^^^^^^^^^^^^^^
+
+Using the ``NEW`` operator you can construct DTOs from queries.
+
+- When using ``SELECT NEW`` you don't need to specify a mapped entity.
+- You can specify any PHP class, it's only require that you have a matching constructor in your class.
+- This approach involves determining exactly which columns you really need,
+  and instantiating data-transfer object that containing a constructor with those arguments.
+
+
+If you want to select data-transfer objects you should create a class:
+
+.. code-block:: php
+
+    <?php
+    class CustomerDTO
+    {
+        public function __construct($name, $email, $city, $value = null)
+        {
+            // Bind values to the object properties.
+        }
+    }
+
+And then use the ``NEW`` DQL keyword :
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, e.email, a.city) FROM Customer c JOIN c.email e JOIN c.address a');
+    $users = $query->getResult(); // array of CustomerDTO
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, e.email, a.city, SUM(o.value)) FROM Customer c JOIN c.email e JOIN c.address a JOIN c.orders o GROUP BY c');
+    $users = $query->getResult(); // array of CustomerDTO
+
 Using INDEX BY
 ~~~~~~~~~~~~~~