Merge pull request #6179 from morozov/deprecate-query-parts

Deprecate getting query parts from QueryBuilder

Author: morozov

UPGRADE.md

@@ -6,6 +6,13 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 3.8
+
+## Deprecated getting query parts from `QueryBuilder`
+
+The usage of `QueryBuilder::getQueryPart()` and `::getQueryParts()` is deprecated. The query parts
+are implementation details and should not be relied upon.
+
 # Upgrade to 3.6
 
 ## Deprecated not setting a schema manager factory

psalm.xml.dist

@@ -499,6 +499,11 @@
                 -->
                 <referencedMethod name="Doctrine\DBAL\Connection::getEventManager"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::setEventManager"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getQueryPart"/>
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getQueryParts"/>
 
                 <!-- TODO for PHPUnit 10 -->
                 <referencedMethod name="PHPUnit\Framework\MockObject\Builder\InvocationMocker::withConsecutive"/>

src/Query/QueryBuilder.php

@@ -1297,22 +1297,38 @@ public function addOrderBy($sort, $order = null)
     /**
      * Gets a query part by its name.
      *
+     * @deprecated The query parts are implementation details and should not be relied upon.
+     *
      * @param string $queryPartName
      *
      * @return mixed
      */
     public function getQueryPart($queryPartName)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6179',
+            'Getting query parts is deprecated as they are implementation details.',
+        );
+
         return $this->sqlParts[$queryPartName];
     }
 
     /**
      * Gets all query parts.
      *
+     * @deprecated The query parts are implementation details and should not be relied upon.
+     *
      * @return mixed[]
      */
     public function getQueryParts()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6179',
+            'Getting query parts is deprecated as they are implementation details.',
+        );
+
         return $this->sqlParts;
     }
 

tests/Query/QueryBuilderTest.php

@@ -12,13 +12,16 @@
 use Doctrine\DBAL\Result;
 use Doctrine\DBAL\Types\Type;
 use Doctrine\DBAL\Types\Types;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
 
 use function hex2bin;
 
 class QueryBuilderTest extends TestCase
 {
+    use VerifyDeprecations;
+
     /** @var Connection&MockObject */
     protected Connection $conn;
 
@@ -792,6 +795,8 @@ public function testClone(): void
 
         $qb->andWhere('u.id = 1');
 
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/6179');
+
         self::assertNotSame($qb->getQueryParts(), $qbClone->getQueryParts());
         self::assertNotSame($qb->getParameters(), $qbClone->getParameters());
     }