Merge 3.4.x into 4.0.x

UPGRADE.md

@@ -817,10 +817,22 @@ The following methods have been removed.
 
 # Upgrade to 3.4
 
+## Deprecated not passing parameter type to the driver-level `Statement::bind*()` methods.
+
+Not passing `$type` to the driver-level `Statement::bindParam()` and `::bindValue()` is deprecated.
+Pass the type corresponding to the parameter being bound.
+
+## Deprecated passing `$params` to `Statement::execute*()` methods.
+
+Passing `$params` to the driver-level `Statement::execute()` and the wrapper-level `Statement::executeQuery()`
+and `Statement::executeStatement()` methods has been deprecated.
+
+Bind parameters using `Statement::bindParam()` or `Statement::bindValue()` instead.
+
 ## 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.
+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:

docs/en/reference/query-builder.rst

@@ -369,3 +369,25 @@ in your query as a return value:
         ->where('email = ' .  $queryBuilder->createPositionalParameter($userInputEmail))
     ;
     // SELECT id, name FROM users WHERE email = ?
+
+Caching
+-------
+
+To use the result cache, it is necessary to call the method
+``enableResultCache($cacheProfile)`` and pass a instance of
+``Doctrine\DBAL\Cache\QueryCacheProfile`` with a cache lifetime
+value in seconds. A cache key can optionally be added if needed.
+
+.. code-block:: php
+
+    <?php
+
+    $queryBuilder
+        ->select('id', 'name')
+        ->from('users')
+        ->enableResultCache(new QueryCacheProfile(300, 'some-key'))
+    ;
+
+.. note::
+
+    See the :ref:`Caching <caching>` section for more information.

src/Connection.php

@@ -838,12 +838,10 @@ public function executeQuery(
                 [$sql, $params, $types] = $this->expandArrayParameters($sql, $params, $types);
 
                 $stmt = $connection->prepare($sql);
-                if (count($types) > 0) {
-                    $this->_bindTypedValues($stmt, $params, $types);
-                    $result = $stmt->execute();
-                } else {
-                    $result = $stmt->execute($params);
-                }
+
+                $this->bindParameters($stmt, $params, $types);
+
+                $result = $stmt->execute();
             } else {
                 $result = $connection->query($sql);
             }
@@ -930,15 +928,10 @@ public function executeStatement(string $sql, array $params = [], array $types =
 
                 $stmt = $connection->prepare($sql);
 
-                if (count($types) > 0) {
-                    $this->_bindTypedValues($stmt, $params, $types);
+                $this->bindParameters($stmt, $params, $types);
 
-                    $result = $stmt->execute();
-                } else {
-                    $result = $stmt->execute($params);
-                }
-
-                return $result->rowCount();
+                return $stmt->execute()
+                    ->rowCount();
             }
 
             return $connection->exec($sql);
@@ -1314,7 +1307,7 @@ public function convertToPHPValue(mixed $value, string $type): mixed
      *
      * @throws Exception
      */
-    private function _bindTypedValues(DriverStatement $stmt, array $params, array $types): void
+    private function bindParameters(DriverStatement $stmt, array $params, array $types): void
     {
         // Check whether parameters are positional or named. Mixing is not allowed.
         if (is_int(key($params))) {
@@ -1324,7 +1317,6 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                 if (isset($types[$key])) {
                     $type                  = $types[$key];
                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
-                    $stmt->bindValue($bindIndex, $value, $bindingType);
                 } else {
                     if (array_key_exists($key, $types)) {
                         Deprecation::trigger(
@@ -1335,9 +1327,11 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                         );
                     }
 
-                    $stmt->bindValue($bindIndex, $value);
+                    $bindingType = ParameterType::STRING;
                 }
 
+                $stmt->bindValue($bindIndex, $value, $bindingType);
+
                 ++$bindIndex;
             }
         } else {
@@ -1346,7 +1340,6 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                 if (isset($types[$name])) {
                     $type                  = $types[$name];
                     [$value, $bindingType] = $this->getBindingInfo($value, $type);
-                    $stmt->bindValue($name, $value, $bindingType);
                 } else {
                     if (array_key_exists($name, $types)) {
                         Deprecation::trigger(
@@ -1357,8 +1350,10 @@ private function _bindTypedValues(DriverStatement $stmt, array $params, array $t
                         );
                     }
 
-                    $stmt->bindValue($name, $value);
+                    $bindingType = ParameterType::STRING;
                 }
+
+                $stmt->bindValue($name, $value, $bindingType);
             }
         }
     }

src/Driver/IBMDB2/Statement.php

@@ -10,12 +10,14 @@
 use Doctrine\DBAL\Driver\IBMDB2\Exception\StatementError;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
 use Doctrine\DBAL\ParameterType;
+use Doctrine\Deprecations\Deprecation;
 
 use function assert;
 use function db2_bind_param;
 use function db2_execute;
 use function error_get_last;
 use function fclose;
+use function func_num_args;
 use function is_int;
 use function is_resource;
 use function stream_copy_to_stream;
@@ -54,6 +56,15 @@ public function bindValue(int|string $param, mixed $value, ParameterType $type =
     {
         assert(is_int($param));
 
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindValue() is deprecated.'
+                    . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->bindParam($param, $value, $type);
     }
 
@@ -65,6 +76,15 @@ public function bindParam(
     ): void {
         assert(is_int($param));
 
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindParam() is deprecated.'
+                    . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         switch ($type) {
             case ParameterType::INTEGER:
                 $this->bind($param, $variable, DB2_PARAM_IN, DB2_LONG);
@@ -94,6 +114,15 @@ private function bind(int $position, mixed &$variable, int $parameterType, int $
 
     public function execute(?array $params = null): Result
     {
+        if ($params !== null) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5556',
+                'Passing $params to Statement::execute() is deprecated. Bind parameters using'
+                    . ' Statement::bindParam() or Statement::bindValue() instead.'
+            );
+        }
+
         $handles = $this->bindLobs();
 
         $result = @db2_execute($this->stmt, $params ?? $this->parameters);

src/Driver/Middleware/AbstractStatementMiddleware.php

@@ -7,6 +7,9 @@
 use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\Statement;
 use Doctrine\DBAL\ParameterType;
+use Doctrine\Deprecations\Deprecation;
+
+use function func_num_args;
 
 abstract class AbstractStatementMiddleware implements Statement
 {
@@ -16,6 +19,15 @@ public function __construct(private readonly Statement $wrappedStatement)
 
     public function bindValue(int|string $param, mixed $value, ParameterType $type = ParameterType::STRING): void
     {
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindValue() is deprecated.'
+                    . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->wrappedStatement->bindValue($param, $value, $type);
     }
 
@@ -25,6 +37,15 @@ public function bindParam(
         ParameterType $type = ParameterType::STRING,
         ?int $length = null
     ): void {
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindParam() is deprecated.'
+                . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->wrappedStatement->bindParam($param, $variable, $type, $length);
     }
 

src/Driver/Mysqli/Statement.php

@@ -10,6 +10,7 @@
 use Doctrine\DBAL\Driver\Mysqli\Exception\StatementError;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
 use Doctrine\DBAL\ParameterType;
+use Doctrine\Deprecations\Deprecation;
 use mysqli_sql_exception;
 use mysqli_stmt;
 
@@ -18,6 +19,7 @@
 use function count;
 use function feof;
 use function fread;
+use function func_num_args;
 use function get_resource_type;
 use function is_int;
 use function is_resource;
@@ -59,6 +61,15 @@ public function bindParam(
     ): void {
         assert(is_int($param));
 
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindParam() is deprecated.'
+                . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->types[$param - 1]   = $this->convertParameterType($type);
         $this->boundValues[$param] =& $variable;
     }
@@ -67,13 +78,31 @@ public function bindValue(int|string $param, mixed $value, ParameterType $type =
     {
         assert(is_int($param));
 
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindValue() is deprecated.'
+                . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->types[$param - 1]   = $this->convertParameterType($type);
         $this->values[$param]      = $value;
         $this->boundValues[$param] =& $this->values[$param];
     }
 
     public function execute(?array $params = null): Result
     {
+        if ($params !== null) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5556',
+                'Passing $params to Statement::execute() is deprecated. Bind parameters using'
+                    . ' Statement::bindParam() or Statement::bindValue() instead.'
+            );
+        }
+
         if ($params !== null && count($params) > 0) {
             $this->bindUntypedValues($params);
         } elseif (count($this->boundValues) > 0) {

src/Driver/OCI8/Statement.php

@@ -8,7 +8,9 @@
 use Doctrine\DBAL\Driver\OCI8\Exception\UnknownParameterIndex;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
 use Doctrine\DBAL\ParameterType;
+use Doctrine\Deprecations\Deprecation;
 
+use function func_num_args;
 use function is_int;
 use function oci_bind_by_name;
 use function oci_execute;
@@ -41,6 +43,15 @@ public function __construct(
 
     public function bindValue(int|string $param, mixed $value, ParameterType $type = ParameterType::STRING): void
     {
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindValue() is deprecated.'
+                . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         $this->bindParam($param, $value, $type);
     }
 
@@ -50,6 +61,15 @@ public function bindParam(
         ParameterType $type = ParameterType::STRING,
         ?int $length = null
     ): void {
+        if (func_num_args() < 3) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5558',
+                'Not passing $type to Statement::bindParam() is deprecated.'
+                    . ' Pass the type corresponding to the parameter being bound.'
+            );
+        }
+
         if (is_int($param)) {
             if (! isset($this->parameterMap[$param])) {
                 throw UnknownParameterIndex::new($param);
@@ -97,14 +117,21 @@ private function convertParameterType(ParameterType $type): int
     public function execute(?array $params = null): Result
     {
         if ($params !== null) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5556',
+                'Passing $params to Statement::execute() is deprecated. Bind parameters using'
+                    . ' Statement::bindParam() or Statement::bindValue() instead.'
+            );
+
             foreach ($params as $key => $val) {
                 if (is_int($key)) {
                     $param = $key + 1;
                 } else {
                     $param = $key;
                 }
 
-                $this->bindValue($param, $val);
+                $this->bindValue($param, $val, ParameterType::STRING);
             }
         }