[GH-8592] Deprecated Named (Native) Queries in Metadata/EntityRepository

docs/en/reference/annotations-reference.rst

@@ -843,6 +843,11 @@ Example:
 
 @NamedNativeQuery
 ~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    Named Native Queries are deprecated as of version 2.9 and will be removed in ORM 3.0
+
 Is used to specify a native SQL named query.
 The NamedNativeQuery annotation can be applied to an entity or mapped superclass.
 

docs/en/reference/native-sql.rst

@@ -71,7 +71,7 @@ with inheritance hierarchies.
 
     use Doctrine\ORM\Query\ResultSetMappingBuilder;
 
-    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " . 
+    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " .
            "FROM users u INNER JOIN address a ON u.address_id = a.id";
 
     $rsm = new ResultSetMappingBuilder($entityManager);
@@ -265,7 +265,7 @@ detail:
     <?php
     /**
      * Adds a meta column (foreign key or discriminator column) to the result set.
-     * 
+     *
      * @param string  $alias
      * @param string  $columnAlias
      * @param string  $columnName
@@ -320,10 +320,10 @@ entity.
     $rsm->addEntityResult('User', 'u');
     $rsm->addFieldResult('u', 'id', 'id');
     $rsm->addFieldResult('u', 'name', 'name');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 The result would look like this:
@@ -356,10 +356,10 @@ thus owns the foreign key.
     $rsm->addFieldResult('u', 'id', 'id');
     $rsm->addFieldResult('u', 'name', 'name');
     $rsm->addMetaResult('u', 'address_id', 'address_id');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name, address_id FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 Foreign keys are used by Doctrine for lazy-loading purposes when
@@ -385,12 +385,12 @@ associations that are lazy.
     $rsm->addFieldResult('a', 'address_id', 'id');
     $rsm->addFieldResult('a', 'street', 'street');
     $rsm->addFieldResult('a', 'city', 'city');
-    
+
     $sql = 'SELECT u.id, u.name, a.id AS address_id, a.street, a.city FROM users u ' .
            'INNER JOIN address a ON u.address_id = a.id WHERE u.name = ?';
     $query = $this->_em->createNativeQuery($sql, $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 In this case the nested entity ``Address`` is registered with the
@@ -420,10 +420,10 @@ to map the hierarchy (both use a discriminator column).
     $rsm->addFieldResult('u', 'name', 'name');
     $rsm->addMetaResult('u', 'discr', 'discr'); // discriminator column
     $rsm->setDiscriminatorColumn('u', 'discr');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 Note that in the case of Class Table Inheritance, an example as
@@ -435,6 +435,10 @@ strategy but with native SQL it is your responsibility.
 Named Native Query
 ------------------
 
+.. note::
+
+    Named Native Queries are deprecated as of version 2.9 and will be removed in ORM 3.0
+
 You can also map a native query using a named native query mapping.
 
 To achieve that, you must describe the SQL resultset structure
@@ -789,7 +793,7 @@ followed by a dot ("."), followed by the name or the field or property of the pr
                     6:
                       name: address.country
                       column: a_country
-                    
+
 
 
 If you retrieve a single entity and if you use the default mapping,

lib/Doctrine/ORM/EntityRepository.php

@@ -109,24 +109,44 @@ public function createResultSetMappingBuilder($alias)
     /**
      * Creates a new Query instance based on a predefined metadata named query.
      *
+     * @deprecated
+     *
      * @param string $queryName
      *
      * @return Query
      */
     public function createNamedQuery($queryName)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryName,
+            $this->_class->name
+        );
+
         return $this->_em->createQuery($this->_class->getNamedQuery($queryName));
     }
 
     /**
      * Creates a native SQL query.
      *
+     * @deprecated
+     *
      * @param string $queryName
      *
      * @return NativeQuery
      */
     public function createNativeNamedQuery($queryName)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryName,
+            $this->_class->name
+        );
+
         $queryMapping = $this->_class->getNamedNativeQuery($queryName);
         $rsm          = new Query\ResultSetMappingBuilder($this->_em);
         $rsm->addNamedNativeQueryMapping($this->_class, $queryMapping);

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -2617,6 +2617,8 @@ public function addInheritedFieldMapping(array $fieldMapping)
      * INTERNAL:
      * Adds a named query to this class.
      *
+     * @deprecated
+     *
      * @return void
      *
      * @throws MappingException
@@ -2629,6 +2631,14 @@ public function addNamedQuery(array $queryMapping)
             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
         }
 
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryMapping['name'],
+            $this->name
+        );
+
         if (isset($this->namedQueries[$queryMapping['name']])) {
             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
         }
@@ -2652,6 +2662,8 @@ public function addNamedQuery(array $queryMapping)
      * INTERNAL:
      * Adds a named native query to this class.
      *
+     * @deprecated
+     *
      * @return void
      *
      * @throws MappingException
@@ -2664,6 +2676,14 @@ public function addNamedNativeQuery(array $queryMapping)
             throw MappingException::nameIsMandatoryForQueryMapping($this->name);
         }
 
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryMapping['name'],
+            $this->name
+        );
+
         if (isset($this->namedNativeQueries[$queryMapping['name']])) {
             throw MappingException::duplicateQueryMapping($this->name, $queryMapping['name']);
         }

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

@@ -499,6 +499,8 @@ public function testFindOneAssociationByMagicCall(): void
 
     public function testValidNamedQueryRetrieval(): void
     {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8592');
+
         $repos = $this->_em->getRepository(CmsUser::class);
 
         $query = $repos->createNamedQuery('all');

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

@@ -5,6 +5,7 @@
 namespace Doctrine\Tests\ORM\Functional;
 
 use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\ORM\Internal\Hydration\HydrationException;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query\Parameter;
@@ -33,6 +34,8 @@
  */
 class NativeQueryTest extends OrmFunctionalTestCase
 {
+    use VerifyDeprecations;
+
     /** @var AbstractPlatform */
     private $platform = null;
 
@@ -405,6 +408,8 @@ public function testBasicNativeNamedQueryWithSqlResultSetMapping(): void
      */
     public function testBasicNativeNamedQueryWithResultClass(): void
     {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8592');
+
         $user           = new CmsUser();
         $user->name     = 'Fabio B. Silva';
         $user->username = 'FabioBatSilva';

tests/Doctrine/Tests/ORM/Functional/Ticket/DDC1404Test.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\Tests\ORM\Functional\Ticket;
 
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\Tests\OrmFunctionalTestCase;
 
 use function count;
@@ -13,6 +14,8 @@
  */
 class DDC1404Test extends OrmFunctionalTestCase
 {
+    use VerifyDeprecations;
+
     protected function setUp(): void
     {
         parent::setUp();
@@ -32,6 +35,8 @@ protected function setUp(): void
 
     public function testTicket(): void
     {
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8592');
+
         $repository  = $this->_em->getRepository(DDC1404ChildEntity::class);
         $queryAll    = $repository->createNamedQuery('all');
         $queryFirst  = $repository->createNamedQuery('first');