From 2ec9b039c300a3febdf6617864f0c250a36ce22a Mon Sep 17 00:00:00 2001
From: Sergei Morozov <morozov@tut.by>
Date: Tue, 10 Oct 2023 11:09:28 +0200
Subject: [PATCH] Deprecate getting query parts from QueryBuilder

---
 UPGRADE.md                       |  7 +++++++
 psalm.xml.dist                   |  5 +++++
 src/Query/QueryBuilder.php       | 16 ++++++++++++++++
 tests/Query/QueryBuilderTest.php |  5 +++++
 4 files changed, 33 insertions(+)

diff --git a/UPGRADE.md b/UPGRADE.md
index 82b42b5fcd8..084d4a68cb5 100644
--- a/UPGRADE.md
+++ b/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
diff --git a/psalm.xml.dist b/psalm.xml.dist
index 567ecc381ae..88948561586 100644
--- a/psalm.xml.dist
+++ b/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"/>
diff --git a/src/Query/QueryBuilder.php b/src/Query/QueryBuilder.php
index ba76fdf9368..ba6598c44c2 100644
--- a/src/Query/QueryBuilder.php
+++ b/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;
     }
 
diff --git a/tests/Query/QueryBuilderTest.php b/tests/Query/QueryBuilderTest.php
index 899a1cd8675..78c420a6a51 100644
--- a/tests/Query/QueryBuilderTest.php
+++ b/tests/Query/QueryBuilderTest.php
@@ -12,6 +12,7 @@
 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;
 
@@ -19,6 +20,8 @@
 
 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());
     }