Merge pull request #10774 from greg0ire/document-dto-in-rsm

docs/en/reference/native-sql.rst

@@ -250,6 +250,40 @@ The first parameter is the name of the column in the SQL result set
 and the second parameter is the result alias under which the value
 of the column will be placed in the transformed Doctrine result.
 
+Special case: DTOs
+...................
+
+You can also use ``ResultSetMapping`` to map the results of a native SQL
+query to a DTO (Data Transfer Object). This is done by adding scalar
+results for each argument of the DTO's constructor, then filling the
+``newObjectMappings`` property of the ``ResultSetMapping`` with
+information about where to map each scalar result:
+
+.. code-block:: php
+
+   <?php
+
+    $rsm = new ResultSetMapping();
+    $rsm->addScalarResult('name', 1, 'string');
+    $rsm->addScalarResult('email', 2, 'string');
+    $rsm->addScalarResult('city', 3, 'string');
+    $rsm->newObjectMappings['name']  = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0, // a result can contain many DTOs, this is the index of the DTO to map to
+        'argIndex'  => 0, // each scalar result can be mapped to a different argument of the DTO constructor
+    ];
+    $rsm->newObjectMappings['email'] = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0,
+        'argIndex'  => 1,
+    ];
+    $rsm->newObjectMappings['city']  = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0,
+        'argIndex'  => 2,
+    ];
+
+
 Meta results
 ~~~~~~~~~~~~
 

tests/Doctrine/Tests/ORM/Functional/NativeQueryTest.php

@@ -19,6 +19,7 @@
 use Doctrine\Tests\Models\CMS\CmsEmail;
 use Doctrine\Tests\Models\CMS\CmsPhonenumber;
 use Doctrine\Tests\Models\CMS\CmsUser;
+use Doctrine\Tests\Models\CMS\CmsUserDTO;
 use Doctrine\Tests\Models\Company\CompanyContract;
 use Doctrine\Tests\Models\Company\CompanyEmployee;
 use Doctrine\Tests\Models\Company\CompanyFixContract;
@@ -155,6 +156,77 @@ public function testJoinedOneToManyNativeQuery(): void
         self::assertSame($phones[0]->getUser(), $users[0]);
     }
 
+    public function testMappingAsDto(): void
+    {
+        $user           = new CmsUser();
+        $user->name     = 'Roman';
+        $user->username = 'romanb';
+        $user->status   = 'dev';
+
+        $phone              = new CmsPhonenumber();
+        $phone->phonenumber = 424242;
+
+        $user->addPhonenumber($phone);
+
+        $email        = new CmsEmail();
+        $email->email = '[email protected]';
+
+        $user->setEmail($email);
+
+        $addr          = new CmsAddress();
+        $addr->country = 'germany';
+        $addr->zip     = 10827;
+        $addr->city    = 'Berlin';
+
+        $user->setAddress($addr);
+
+        $this->_em->persist($user);
+        $this->_em->flush();
+
+        $this->_em->clear();
+
+        $rsm = new ResultSetMapping();
+        $rsm->addScalarResult('name', 1, 'string');
+        $rsm->addScalarResult('email', 2, 'string');
+        $rsm->addScalarResult('city', 3, 'string');
+        $rsm->newObjectMappings['name']  = [
+            'className' => CmsUserDTO::class,
+            'objIndex'  => 0,
+            'argIndex'  => 0,
+        ];
+        $rsm->newObjectMappings['email'] = [
+            'className' => CmsUserDTO::class,
+            'objIndex'  => 0,
+            'argIndex'  => 1,
+        ];
+        $rsm->newObjectMappings['city']  = [
+            'className' => CmsUserDTO::class,
+            'objIndex'  => 0,
+            'argIndex'  => 2,
+        ];
+        $query                           = $this->_em->createNativeQuery(
+            <<<'SQL'
+    SELECT u.name, e.email, a.city
+      FROM cms_users u
+INNER JOIN cms_phonenumbers p ON u.id = p.user_id
+INNER JOIN cms_emails e ON e.id = u.email_id
+INNER JOIN cms_addresses a ON u.id = a.user_id
+     WHERE username = ?
+SQL
+            ,
+            $rsm
+        );
+        $query->setParameter(1, 'romanb');
+
+        $users = $query->getResult();
+        self::assertCount(1, $users);
+        $user = $users[0];
+        self::assertInstanceOf(CmsUserDTO::class, $user);
+        self::assertEquals('Roman', $user->name);
+        self::assertEquals('[email protected]', $user->email);
+        self::assertEquals('Berlin', $user->address);
+    }
+
     public function testJoinedOneToOneNativeQuery(): void
     {
         $user           = new CmsUser();