Deprecate PingableConnection in favor of handling lost connection

UPGRADE.md

@@ -1,5 +1,13 @@
 # Upgrade to 2.11
 
+## Statement constructors are marked internal
+
+The driver and wrapper statement objects can be only created by the corresponding connection objects.
+
+## The `PingableConnection` interface is deprecated
+
+The wrapper connection will automatically handle the lost connection if the driver supports reporting it.
+
 ## The `ExceptionConverterDriver` interface is deprecated
 
 All drivers will have to implement the exception conversion API.

lib/Doctrine/DBAL/Connection.php

@@ -13,6 +13,7 @@
 use Doctrine\DBAL\Driver\PingableConnection;
 use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Exception\ConnectionLost;
 use Doctrine\DBAL\Exception\InvalidArgumentException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
@@ -614,7 +615,7 @@ public function fetchAssociative(string $query, array $params = [], array $types
 
             return $stmt->fetch(FetchMode::ASSOCIATIVE);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -641,7 +642,7 @@ public function fetchNumeric(string $query, array $params = [], array $types = [
 
             return $stmt->fetch(FetchMode::NUMERIC);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -668,7 +669,7 @@ public function fetchOne(string $query, array $params = [], array $types = [])
 
             return $stmt->fetch(FetchMode::COLUMN);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -952,7 +953,7 @@ public function fetchAllNumeric(string $query, array $params = [], array $types
 
             return $stmt->fetchAll(FetchMode::NUMERIC);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -978,7 +979,7 @@ public function fetchAllAssociative(string $query, array $params = [], array $ty
 
             return $stmt->fetchAll(FetchMode::ASSOCIATIVE);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -1004,7 +1005,7 @@ public function fetchFirstColumn(string $query, array $params = [], array $types
 
             return $stmt->fetchAll(FetchMode::COLUMN);
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -1032,7 +1033,7 @@ public function iterateNumeric(string $query, array $params = [], array $types =
                 }
             }
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -1060,7 +1061,7 @@ public function iterateAssociative(string $query, array $params = [], array $typ
                 }
             }
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -1088,7 +1089,7 @@ public function iterateColumn(string $query, array $params = [], array $types =
                 }
             }
         } catch (Throwable $e) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
     }
 
@@ -1105,8 +1106,8 @@ public function prepare($statement)
     {
         try {
             $stmt = new Statement($statement, $this);
-        } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $statement);
+        } catch (Throwable $e) {
+            $this->handleExceptionDuringQuery($e, $statement);
         }
 
         $stmt->setFetchMode($this->defaultFetchMode);
@@ -1156,8 +1157,8 @@ public function executeQuery($query, array $params = [], $types = [], ?QueryCach
             } else {
                 $stmt = $connection->query($query);
             }
-        } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $query, $this->resolveParams($params, $types));
+        } catch (Throwable $e) {
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
 
         $stmt->setFetchMode($this->defaultFetchMode);
@@ -1263,8 +1264,8 @@ public function query()
 
         try {
             $statement = $connection->query(...$args);
-        } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $args[0]);
+        } catch (Throwable $e) {
+            $this->handleExceptionDuringQuery($e, $args[0]);
         }
 
         $statement->setFetchMode($this->defaultFetchMode);
@@ -1316,8 +1317,8 @@ public function executeUpdate($query, array $params = [], array $types = [])
             } else {
                 $result = $connection->exec($query);
             }
-        } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $query, $this->resolveParams($params, $types));
+        } catch (Throwable $e) {
+            $this->handleExceptionDuringQuery($e, $query, $params, $types);
         }
 
         if ($logger) {
@@ -1347,8 +1348,8 @@ public function exec($statement)
 
         try {
             $result = $connection->exec($statement);
-        } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $statement);
+        } catch (Throwable $e) {
+            $this->handleExceptionDuringQuery($e, $statement);
         }
 
         if ($logger) {
@@ -1924,6 +1925,8 @@ public function createQueryBuilder()
      * It is responsibility of the developer to handle this case
      * and abort the request or reconnect manually:
      *
+     * @deprecated
+     *
      * @return bool
      *
      * @example
@@ -1954,4 +1957,59 @@ public function ping()
             return false;
         }
     }
+
+    /**
+     * @internal
+     *
+     * @param array<int, mixed>|array<string, mixed>           $params
+     * @param array<int, int|string>|array<string, int|string> $types
+     *
+     * @throws DBALException
+     *
+     * @psalm-return never-return
+     */
+    public function handleExceptionDuringQuery(Throwable $e, string $sql, array $params = [], array $types = []): void
+    {
+        $this->throw(
+            DBALException::driverExceptionDuringQuery(
+                $this->_driver,
+                $e,
+                $sql,
+                $this->resolveParams($params, $types)
+            )
+        );
+    }
+
+    /**
+     * @internal
+     *
+     * @throws DBALException
+     *
+     * @psalm-return never-return
+     */
+    public function handleDriverException(Throwable $e): void
+    {
+        $this->throw(
+            DBALException::driverException(
+                $this->_driver,
+                $e
+            )
+        );
+    }
+
+    /**
+     * @internal
+     *
+     * @throws DBALException
+     *
+     * @psalm-return never-return
+     */
+    private function throw(DBALException $e): void
+    {
+        if ($e instanceof ConnectionLost) {
+            $this->close();
+        }
+
+        throw $e;
+    }
 }

lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\DriverException as DeprecatedDriverException;
 use Doctrine\DBAL\Exception\ConnectionException;
+use Doctrine\DBAL\Exception\ConnectionLost;
 use Doctrine\DBAL\Exception\DeadlockException;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
@@ -108,6 +109,9 @@ public function convertException($message, DeprecatedDriverException $exception)
             case '2005':
                 return new ConnectionException($message, $exception);
 
+            case '2006':
+                return new ConnectionLost($message, $exception);
+
             case '1048':
             case '1121':
             case '1138':

lib/Doctrine/DBAL/Driver/IBMDB2/DB2Statement.php

@@ -92,6 +92,8 @@ class DB2Statement implements IteratorAggregate, StatementInterface, Result
     private $result = false;
 
     /**
+     * @internal The statement can be only instantiated by its driver connection.
+     *
      * @param resource $stmt
      */
     public function __construct($stmt)

lib/Doctrine/DBAL/Driver/Mysqli/MysqliConnection.php

@@ -281,6 +281,8 @@ private function setDriverOptions(array $driverOptions = []): void
     /**
      * Pings the server and re-connects when `mysqli.reconnect = 1`
      *
+     * @deprecated
+     *
      * @return bool
      */
     public function ping()

lib/Doctrine/DBAL/Driver/Mysqli/MysqliStatement.php

@@ -82,6 +82,8 @@ class MysqliStatement implements IteratorAggregate, StatementInterface, Result
     private $result = false;
 
     /**
+     * @internal The statement can be only instantiated by its driver connection.
+     *
      * @param string $prepareString
      *
      * @throws MysqliException

lib/Doctrine/DBAL/Driver/OCI8/OCI8Statement.php

@@ -105,6 +105,8 @@ class OCI8Statement implements IteratorAggregate, StatementInterface, Result
     /**
      * Creates a new OCI8Statement that uses the given connection handle and SQL statement.
      *
+     * @internal The statement can be only instantiated by its driver connection.
+     *
      * @param resource $dbh   The connection handle.
      * @param string   $query The SQL query.
      */

lib/Doctrine/DBAL/Driver/PDOStatement.php

@@ -46,6 +46,8 @@ class PDOStatement extends \PDOStatement implements StatementInterface, Result
 
     /**
      * Protected constructor.
+     *
+     * @internal The statement can be only instantiated by its driver connection.
      */
     protected function __construct()
     {

lib/Doctrine/DBAL/Driver/PingableConnection.php

@@ -4,6 +4,8 @@
 
 /**
  * An interface for connections which support a "native" ping method.
+ *
+ * @deprecated
  */
 interface PingableConnection
 {

lib/Doctrine/DBAL/Driver/SQLAnywhere/SQLAnywhereStatement.php

@@ -71,6 +71,8 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement, Result
     /**
      * Prepares given statement for given connection.
      *
+     * @internal The statement can be only instantiated by its driver connection.
+     *
      * @param resource $conn The connection resource to use.
      * @param string   $sql  The SQL statement to prepare.
      *

lib/Doctrine/DBAL/Driver/SQLSrv/SQLSrvStatement.php

@@ -136,6 +136,8 @@ class SQLSrvStatement implements IteratorAggregate, StatementInterface, Result
     public const LAST_INSERT_ID_SQL = ';SELECT SCOPE_IDENTITY() AS LastInsertId;';
 
     /**
+     * @internal The statement can be only instantiated by its driver connection.
+     *
      * @param resource $conn
      * @param string   $sql
      */

lib/Doctrine/DBAL/Exception/ConnectionLost.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Doctrine\DBAL\Exception;
+
+/**
+ * @psalm-immutable
+ */
+final class ConnectionLost extends ConnectionException
+{
+}