From d3664d02d44d26799ebbc43d16cb702e74587428 Mon Sep 17 00:00:00 2001
From: "Alexander M. Turek" <me@derrabus.de>
Date: Sun, 31 Jul 2022 16:19:59 +0200
Subject: [PATCH] Deprecate QueryBuilder APIs exposing its internal state

Co-authored-by: Sergei Morozov <morozov@tut.by>
---
 UPGRADE.md                        | 14 ++++++++++++++
 lib/Doctrine/ORM/QueryBuilder.php | 27 +++++++++++++++++++++++++--
 psalm.xml                         |  1 +
 3 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/UPGRADE.md b/UPGRADE.md
index b85b1c74b3f..a367589573f 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -1,5 +1,19 @@
 # Upgrade to 2.13
 
+## Deprecated `QueryBuilder` methods and constants.
+
+1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.
+2. Relying on the type of the query being built by using `QueryBuilder::getType()` has been deprecated.
+   If necessary, track the type of the query being built outside of the builder.
+
+The following `QueryBuilder` constants related to the above methods have been deprecated:
+
+1. `SELECT`,
+2. `DELETE`,
+3. `UPDATE`,
+4. `STATE_DIRTY`,
+5. `STATE_CLEAN`.
+
 ## Deprecated omitting only the alias argument for `QueryBuilder::update` and `QueryBuilder::delete`
 
 When building an UPDATE or DELETE query and when passing a class/type to the function, the alias argument must not be omitted.
diff --git a/lib/Doctrine/ORM/QueryBuilder.php b/lib/Doctrine/ORM/QueryBuilder.php
index a0504758a2b..4003615081a 100644
--- a/lib/Doctrine/ORM/QueryBuilder.php
+++ b/lib/Doctrine/ORM/QueryBuilder.php
@@ -39,13 +39,19 @@
  */
 class QueryBuilder
 {
-    /* The query types. */
+    /** @deprecated */
     public const SELECT = 0;
+
+    /** @deprecated */
     public const DELETE = 1;
+
+    /** @deprecated */
     public const UPDATE = 2;
 
-    /* The builder states. */
+    /** @deprecated */
     public const STATE_DIRTY = 0;
+
+    /** @deprecated */
     public const STATE_CLEAN = 1;
 
     /**
@@ -275,11 +281,20 @@ public function setCacheMode($cacheMode)
     /**
      * Gets the type of the currently built query.
      *
+     * @deprecated If necessary, track the type of the query being built outside of the builder.
+     *
      * @return int
      * @psalm-return self::SELECT|self::DELETE|self::UPDATE
      */
     public function getType()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/orm/pull/9945',
+            'Relying on the type of the query being built is deprecated.'
+            . ' If necessary, track the type of the query being built outside of the builder.'
+        );
+
         return $this->_type;
     }
 
@@ -296,11 +311,19 @@ public function getEntityManager()
     /**
      * Gets the state of this query builder instance.
      *
+     * @deprecated The builder state is an internal concern.
+     *
      * @return int Either QueryBuilder::STATE_DIRTY or QueryBuilder::STATE_CLEAN.
      * @psalm-return self::STATE_*
      */
     public function getState()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/orm/pull/9945',
+            'Relying on the query builder state is deprecated as it is an internal concern.'
+        );
+
         return $this->_state;
     }
 
diff --git a/psalm.xml b/psalm.xml
index 4b148a8162e..dd985cf7a64 100644
--- a/psalm.xml
+++ b/psalm.xml
@@ -43,6 +43,7 @@
                 <file name="lib/Doctrine/ORM/Configuration.php"/>
                 <file name="lib/Doctrine/ORM/Query/Lexer.php"/>
                 <file name="lib/Doctrine/ORM/Query/Parser.php"/>
+                <file name="lib/Doctrine/ORM/QueryBuilder.php"/>
             </errorLevel>
         </DeprecatedConstant>
         <DeprecatedInterface>