Merge pull request #5551 from morozov/deprecate-query-builder-internals

Deprecate QueryBuilder APIs exposing its internal state

UPGRADE.md

@@ -8,6 +8,21 @@ awareness about deprecated code.
 
 # Upgrade to 3.4
 
+## 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 is deprecated 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. `INSERT`,
+5. `STATE_DIRTY`,
+6. `STATE_CLEAN`.
+
 ## Marked `Connection::ARRAY_PARAM_OFFSET` as internal.
 
 The `Connection::ARRAY_PARAM_OFFSET` constant has been marked as internal. It will be removed in 4.0.

psalm.xml.dist

@@ -111,6 +111,11 @@
                 <file name="src/Types/ObjectType.php"/>
                 <file name="src/Types/Type.php"/>
                 <file name="tests/Schema/ComparatorTest.php"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <file name="src/Query/QueryBuilder.php"/>
+                <file name="tests/Query/QueryBuilderTest.php"/>
             </errorLevel>
         </DeprecatedConstant>
         <DeprecatedInterface>
@@ -389,6 +394,11 @@
                 -->
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getIndexFieldDeclarationListSQL"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getCustomTypeDeclarationSQL"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getState"/>
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getType"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>

src/Query/QueryBuilder.php

@@ -37,18 +37,34 @@
  */
 class QueryBuilder
 {
-    /*
-     * The query types.
+    /**
+     * @deprecated
      */
     public const SELECT = 0;
+
+    /**
+     * @deprecated
+     */
     public const DELETE = 1;
+
+    /**
+     * @deprecated
+     */
     public const UPDATE = 2;
+
+    /**
+     * @deprecated
+     */
     public const INSERT = 3;
 
-    /*
-     * The builder states.
+    /**
+     * @deprecated
      */
     public const STATE_DIRTY = 0;
+
+    /**
+     * @deprecated
+     */
     public const STATE_CLEAN = 1;
 
     /**
@@ -157,10 +173,19 @@ public function expr()
     /**
      * 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
      */
     public function getType()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5551',
+            '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;
     }
 
@@ -177,10 +202,18 @@ public function getConnection()
     /**
      * 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.
      */
     public function getState()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5551',
+            'Relying on the query builder state is deprecated as it is an internal concern.'
+        );
+
         return $this->state;
     }