Deprecate QueryBuilder APIs exposing its internal state

Co-authored-by: Sergei Morozov <morozov@tut.by>

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.

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;
     }
 

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>