Introduce a ArrayParameterType enum

doctrine · Dec 29, 2022 · 7389c86 · 7389c86
1 parent af57bbf
commit 7389c86
Show file tree

Hide file tree

Showing 11 changed files with 253 additions and 175 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -8,6 +8,10 @@ awareness about deprecated code.
 
 # Upgrade to 4.0
 
+## Removed `Connection::PARAM_*_ARRAY` constants
+
+Use the enum `ArrayParameterType` instead.
+
 ## Disallowed partial version numbers in ``serverVersion``
 
 The ``serverVersion`` connection parameter must consist of 3 numbers:
@@ -853,6 +857,13 @@ The following methods have been removed.
 | `QueryCacheProfile` | `setResultCacheDriver()` | `setResultCache()` |
 | `QueryCacheProfile` | `getResultCacheDriver()` | `getResultCache()` |
 
+# Upgrade to 3.6
+
+## Deprecated `Connection::PARAM_*_ARRAY` constants
+
+Use the corresponding constants on `ArrayParameterType` instead. Please be aware that
+`ArrayParameterType` will be a native enum type in DBAL 4.
+
 # Upgrade to 3.5
 
 ## Deprecated extension via Doctrine Event Manager

diff --git a/src/ArrayParameterType.php b/src/ArrayParameterType.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL;
+
+enum ArrayParameterType
+{
+    /**
+     * Represents an array of ints to be expanded by Doctrine SQL parsing.
+     */
+    case INTEGER;
+
+    /**
+     * Represents an array of strings to be expanded by Doctrine SQL parsing.
+     */
+    case STRING;
+
+    /**
+     * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
+     */
+    case ASCII;
+
+    /** @internal */
+    public static function toElementParameterType(self $type): ParameterType
+    {
+        return match ($type) {
+            self::INTEGER => ParameterType::INTEGER,
+            self::STRING => ParameterType::STRING,
+            self::ASCII => ParameterType::ASCII,
+        };
+    }
+}
diff --git a/src/Cache/QueryCacheProfile.php b/src/Cache/QueryCacheProfile.php
@@ -5,8 +5,7 @@
 namespace Doctrine\DBAL\Cache;
 
 use Doctrine\DBAL\Cache\Exception\NoCacheKey;
-use Doctrine\DBAL\ParameterType;
-use Doctrine\DBAL\Types\Type;
+use Doctrine\DBAL\Connection;
 use Psr\Cache\CacheItemPoolInterface;
 
 use function hash;
@@ -17,6 +16,8 @@
  * Query Cache Profile handles the data relevant for query caching.
  *
  * It is a value object, setter methods return NEW instances.
+ *
+ * @psalm-import-type WrapperParameterType from Connection
  */
 class QueryCacheProfile
 {
@@ -50,9 +51,9 @@ public function getCacheKey(): string
     /**
      * Generates the real cache key from query, params, types and connection parameters.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
-     * @param array<string, mixed>                                                                   $connectionParams
+     * @param list<mixed>|array<string, mixed> $params
+     * @param array<string, mixed>             $connectionParams
+     * @psalm-param array<int, WrapperParameterType>|array<string, WrapperParameterType> $types
      *
      * @return array{string, string}
      */

diff --git a/src/Connection.php b/src/Connection.php
@@ -43,25 +43,12 @@
  * configuration, emulated transaction nesting, lazy connecting and more.
  *
  * @psalm-import-type Params from DriverManager
+ * @psalm-type WrapperParameterType = string|Type|ParameterType|ArrayParameterType
+ * @psalm-type WrapperParameterTypeArray = array<int, WrapperParameterType>|array<string, WrapperParameterType>
  * @psalm-consistent-constructor
  */
 class Connection implements ServerVersionProvider
 {
-    /**
-     * Represents an array of integers to be expanded by Doctrine SQL parsing.
-     */
-    final public const PARAM_INT_ARRAY = 101;
-
-    /**
-     * Represents an array of strings to be expanded by Doctrine SQL parsing.
-     */
-    final public const PARAM_STR_ARRAY = 102;
-
-    /**
-     * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
-     */
-    final public const PARAM_ASCII_STR_ARRAY = 117;
-
     /**
      * The wrapped driver connection.
      */
@@ -284,8 +271,8 @@ public function setAutoCommit(bool $autoCommit): void
      * Prepares and executes an SQL query and returns the first row of the result
      * as an associative array.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return array<string, mixed>|false False is returned if no rows are found.
      *
@@ -300,8 +287,8 @@ public function fetchAssociative(string $query, array $params = [], array $types
      * Prepares and executes an SQL query and returns the first row of the result
      * as a numerically indexed array.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return list<mixed>|false False is returned if no rows are found.
      *
@@ -316,8 +303,8 @@ public function fetchNumeric(string $query, array $params = [], array $types = [
      * Prepares and executes an SQL query and returns the value of a single column
      * of the first row of the result.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return mixed|false False is returned if no rows are found.
      *
@@ -379,8 +366,8 @@ private function addCriteriaCondition(
      *
      * Table expression and columns are not escaped and are not safe for user-input.
      *
-     * @param array<string, mixed>                                                                   $criteria
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<string, mixed>                                                           $criteria
+     * @param array<int, string|ParameterType|Type>|array<string, string|ParameterType|Type> $types
      *
      * @return int|string The number of affected rows.
      *
@@ -445,9 +432,9 @@ public function getTransactionIsolation(): TransactionIsolationLevel
      *
      * Table expression and columns are not escaped and are not safe for user-input.
      *
-     * @param array<string, mixed>                                                                   $data
-     * @param array<string, mixed>                                                                   $criteria
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<string, mixed>                                                           $data
+     * @param array<string, mixed>                                                           $criteria
+     * @param array<int, string|ParameterType|Type>|array<string, string|ParameterType|Type> $types
      *
      * @return int|string The number of affected rows.
      *
@@ -483,8 +470,8 @@ public function update(string $table, array $data, array $criteria = [], array $
      *
      * Table expression and columns are not escaped and are not safe for user-input.
      *
-     * @param array<string, mixed>                                                                   $data
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<string, mixed>                                                           $data
+     * @param array<int, string|ParameterType|Type>|array<string, string|ParameterType|Type> $types
      *
      * @return int|string The number of affected rows.
      *
@@ -517,10 +504,10 @@ public function insert(string $table, array $data, array $types = []): int|strin
     /**
      * Extract ordered type list from an ordered column list and type map.
      *
-     * @param array<int, string>                                                                     $columns
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<int, string>                                                             $columns
+     * @param array<int, string|ParameterType|Type>|array<string, string|ParameterType|Type> $types
      *
-     * @return array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type>
+     * @return array<int, string|ParameterType|Type>|array<string, string|ParameterType|Type>
      */
     private function extractTypeValues(array $columns, array $types): array
     {
@@ -564,8 +551,8 @@ public function quote(string $value): string
     /**
      * Prepares and executes an SQL query and returns the result as an array of numeric arrays.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return list<list<mixed>>
      *
@@ -579,8 +566,8 @@ public function fetchAllNumeric(string $query, array $params = [], array $types
     /**
      * Prepares and executes an SQL query and returns the result as an array of associative arrays.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return list<array<string,mixed>>
      *
@@ -595,8 +582,8 @@ public function fetchAllAssociative(string $query, array $params = [], array $ty
      * Prepares and executes an SQL query and returns the result as an associative array with the keys
      * mapped to the first column and the values mapped to the second column.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return array<mixed,mixed>
      *
@@ -612,8 +599,8 @@ public function fetchAllKeyValue(string $query, array $params = [], array $types
      * to the first column and the values being an associative array representing the rest of the columns
      * and their values.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return array<mixed,array<string,mixed>>
      *
@@ -627,8 +614,8 @@ public function fetchAllAssociativeIndexed(string $query, array $params = [], ar
     /**
      * Prepares and executes an SQL query and returns the result as an array of the first column values.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return list<mixed>
      *
@@ -642,8 +629,8 @@ public function fetchFirstColumn(string $query, array $params = [], array $types
     /**
      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return Traversable<int,list<mixed>>
      *
@@ -658,8 +645,8 @@ public function iterateNumeric(string $query, array $params = [], array $types =
      * Prepares and executes an SQL query and returns the result as an iterator over rows represented
      * as associative arrays.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return Traversable<int,array<string,mixed>>
      *
@@ -674,8 +661,8 @@ public function iterateAssociative(string $query, array $params = [], array $typ
      * Prepares and executes an SQL query and returns the result as an iterator with the keys
      * mapped to the first column and the values mapped to the second column.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return Traversable<mixed,mixed>
      *
@@ -691,9 +678,8 @@ public function iterateKeyValue(string $query, array $params = [], array $types
      * to the first column and the values being an associative array representing the rest of the columns
      * and their values.
      *
-     * @param string                                                               $query  SQL query
-     * @param list<mixed>|array<string, mixed>                                     $params
-     * @param array<int, ParameterType|string>|array<string, ParameterType|string> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return Traversable<mixed,array<string,mixed>>
      *
@@ -707,8 +693,8 @@ public function iterateAssociativeIndexed(string $query, array $params = [], arr
     /**
      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return Traversable<int,mixed>
      *
@@ -744,8 +730,8 @@ public function prepare(string $sql): Statement
      *
      * If the query is parametrized, a prepared statement is used.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @throws Exception
      */
@@ -783,8 +769,8 @@ public function executeQuery(
     /**
      * Executes a caching query.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @throws CacheException
      * @throws Exception
@@ -838,8 +824,8 @@ public function executeCacheQuery(string $sql, array $params, array $types, Quer
      *
      * This method supports PDO binding types as well as DBAL mapping types.
      *
-     * @param list<mixed>|array<string, mixed>                                                       $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @throws Exception
      */
@@ -1290,8 +1276,8 @@ public function createQueryBuilder(): QueryBuilder
     /**
      * @internal
      *
-     * @param list<mixed>|array<string,mixed>                                                        $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param list<mixed>|array<string,mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      */
     final public function convertExceptionDuringQuery(
         Driver\Exception $e,
@@ -1309,8 +1295,8 @@ final public function convertException(Driver\Exception $e): DriverException
     }
 
     /**
-     * @param array<int, mixed>|array<string, mixed>                                                 $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<int, mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @return array{
      *     string,
@@ -1327,7 +1313,7 @@ private function expandArrayParameters(string $sql, array $params, array $types)
             $needsConversion = true;
         } else {
             foreach ($types as $key => $type) {
-                if (is_int($type)) {
+                if ($type instanceof ArrayParameterType) {
                     $needsConversion = true;
                     break;
                 }
@@ -1371,8 +1357,8 @@ private function handleDriverException(
      *
      * @deprecated This API is deprecated and will be removed after 2022
      *
-     * @param array<int, mixed>|array<string, mixed>                                                 $params
-     * @param array<int, int|string|ParameterType|Type>|array<string, int|string|ParameterType|Type> $types
+     * @param array<int, mixed>|array<string, mixed> $params
+     * @psalm-param WrapperParameterTypeArray $types
      *
      * @throws Exception
      */