Merge branch '3.4.x' into 4.0.x

doctrine · Jul 30, 2022 · bf00d39 · bf00d39
2 parents 1c43874 + e80b11c
commit bf00d39
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 15 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -791,6 +791,29 @@ The following methods have been removed.
 
 # 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.
+
+## Deprecated using NULL as prepared statement parameter type.
+
+Omit the type or use `Parameter::STRING` instead.
+
 ## Deprecated passing asset names as assets in `AbstractPlatform` and `AbstractSchemaManager` methods.
 
 Passing assets to the following `AbstractPlatform` methods and parameters has been deprecated:

diff --git a/psalm.xml.dist b/psalm.xml.dist
@@ -32,13 +32,27 @@
                 <file name="src/Driver/OCI8/ConvertPositionalToNamedPlaceholders.php"/>
             </errorLevel>
         </ConflictingReferenceConstraint>
+        <DeprecatedConstant>
+            <errorLevel type="suppress">
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <file name="src/Query/QueryBuilder.php"/>
+                <file name="tests/Query/QueryBuilderTest.php"/>
+            </errorLevel>
+        </DeprecatedConstant>
         <DeprecatedMethod>
             <errorLevel type="suppress">
                 <!--
                     This suppression should be removed after 2022
                     See https://github.com/doctrine/dbal/pull/4317
                 -->
                 <file name="tests/Functional/LegacyAPITest.php"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getState"/>
+                <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getType"/>
             </errorLevel>
         </DeprecatedMethod>
         <DocblockTypeContradiction>

diff --git a/src/Connection.php b/src/Connection.php
@@ -35,6 +35,7 @@
 use Throwable;
 use Traversable;
 
+use function array_key_exists;
 use function assert;
 use function count;
 use function implode;
@@ -69,6 +70,8 @@ class Connection implements ServerVersionProvider
 
     /**
      * Offset by which PARAM_* constants are detected as arrays of the param type.
+     *
+     * @internal Should be used only within the wrapper layer.
      */
     final public const ARRAY_PARAM_OFFSET = 100;
 
@@ -1338,6 +1341,15 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
                     $stmt->bindValue($bindIndex, $value, $bindingType);
                 } else {
+                    if (array_key_exists($key, $types)) {
+                        Deprecation::trigger(
+                            'doctrine/dbal',
+                            'https://github.com/doctrine/dbal/pull/5550',
+                            'Using NULL as prepared statement parameter type is deprecated.'
+                                . 'Omit or use Parameter::STRING instead'
+                        );
+                    }
+
                     $stmt->bindValue($bindIndex, $value);
                 }
 
@@ -1351,6 +1363,15 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
                     $stmt->bindValue($name, $value, $bindingType);
                 } else {
+                    if (array_key_exists($name, $types)) {
+                        Deprecation::trigger(
+                            'doctrine/dbal',
+                            'https://github.com/doctrine/dbal/pull/5550',
+                            'Using NULL as prepared statement parameter type is deprecated.'
+                                . 'Omit or use Parameter::STRING instead'
+                        );
+                    }
+
                     $stmt->bindValue($name, $value);
                 }
             }

diff --git a/src/Query/QueryBuilder.php b/src/Query/QueryBuilder.php
@@ -14,6 +14,7 @@
 use Doctrine\DBAL\Result;
 use Doctrine\DBAL\Statement;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_key_exists;
 use function array_keys;
@@ -36,18 +37,34 @@
  */
 class QueryBuilder
 {
-    /*
-     * The query types.
+    /**
+     * @deprecated
      */
     final public const SELECT = 0;
+
+    /**
+     * @deprecated
+     */
     final public const DELETE = 1;
+
+    /**
+     * @deprecated
+     */
     final public const UPDATE = 2;
+
+    /**
+     * @deprecated
+     */
     final public const INSERT = 3;
 
-    /*
-     * The builder states.
+    /**
+     * @deprecated
      */
     final public const STATE_DIRTY = 0;
+
+    /**
+     * @deprecated
+     */
     final public const STATE_CLEAN = 1;
 
     /**
@@ -193,9 +210,18 @@ public function expr(): ExpressionBuilder
 
     /**
      * Gets the type of the currently built query.
+     *
+     * @deprecated If necessary, track the type of the query being built outside of the builder.
      */
     public function getType(): int
     {
+        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;
     }
 
@@ -210,10 +236,18 @@ public function getConnection(): Connection
     /**
      * 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(): int
     {
+        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;
     }
 
@@ -393,10 +427,20 @@ public function getSQL(): string
      *
      * @return $this This QueryBuilder instance.
      */
-    public function setParameter(int|string $key, mixed $value, int|string|Type|null $type = null): self
-    {
+    public function setParameter(
+        int|string $key,
+        mixed $value,
+        int|string|Type|null $type = ParameterType::STRING
+    ): self {
         if ($type !== null) {
             $this->paramTypes[$key] = $type;
+        } else {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5550',
+                'Using NULL as prepared statement parameter type is deprecated.'
+                    . 'Omit or use Parameter::STRING instead'
+            );
         }
 
         $this->params[$key] = $value;
@@ -469,11 +513,11 @@ public function getParameterTypes(): array
      *
      * @param int|string $key The key of the bound parameter type
      *
-     * @return int|string|Type|null The value of the bound parameter type
+     * @return int|string|Type The value of the bound parameter type
      */
     public function getParameterType(int|string $key): int|string|Type|null
     {
-        return $this->paramTypes[$key] ?? null;
+        return $this->paramTypes[$key] ?? ParameterType::STRING;
     }
 
     /**

diff --git a/tests/Query/QueryBuilderTest.php b/tests/Query/QueryBuilderTest.php
@@ -797,16 +797,16 @@ public function testGetParameterType(): void
 
         $qb->select('*')->from('users');
 
-        self::assertNull($qb->getParameterType('name'));
+        self::assertSame(ParameterType::STRING, $qb->getParameterType('name'));
 
         $qb->where('name = :name');
         $qb->setParameter('name', 'foo');
 
-        self::assertNull($qb->getParameterType('name'));
+        self::assertSame(ParameterType::STRING, $qb->getParameterType('name'));
 
-        $qb->setParameter('name', 'foo', ParameterType::STRING);
+        $qb->setParameter('name', 'foo', ParameterType::INTEGER);
 
-        self::assertSame(ParameterType::STRING, $qb->getParameterType('name'));
+        self::assertSame(ParameterType::INTEGER, $qb->getParameterType('name'));
     }
 
     public function testGetParameterTypes(): void
@@ -820,9 +820,9 @@ public function testGetParameterTypes(): void
         $qb->where('name = :name');
         $qb->setParameter('name', 'foo');
 
-        self::assertSame([], $qb->getParameterTypes());
-
-        $qb->setParameter('name', 'foo', ParameterType::STRING);
+        self::assertSame([
+            'name' => ParameterType::STRING,
+        ], $qb->getParameterTypes());
 
         $qb->where('is_active = :isActive');
         $qb->setParameter('isActive', true, ParameterType::BOOLEAN);