Deprecate inconsistently and ambiguously named driver-level classes

UPGRADE.md

@@ -1,5 +1,37 @@
 # Upgrade to 2.11
 
+## Inconsistently and ambiguously named driver-level classes are deprecated
+
+The following classes under the `Driver` namespace have been deprecated in favor of their consistently named counterparts:
+
+- `DriverException` → `Exception`
+- `AbstractDriverException` → `AbstractException`
+- `IBMDB2\DB2Driver` → `IBMDB2\Driver`
+- `IBMDB2\DB2Connection` → `IBMDB2\Connection`
+- `IBMDB2\DB2Statement` → `IBMDB2\Statement`
+- `Mysqli\MysqliConnection` → `Mysqli\Connection`
+- `Mysqli\MysqliStatement` → `Mysqli\Statement`
+- `OCI8\OCI8Connection` → `OCI8\Connection`
+- `OCI8\OCI8Statement` → `OCI8\Statement`
+- `SQLSrv\SQLSrvConnection` → `SQLSrv\Connection`
+- `SQLSrv\SQLSrvStatement` → `SQLSrv\Statement`
+- `PDOConnection` → `PDO\Connection`
+- `PDOStatement` → `PDO\Statement`
+
+All driver-specific exception classes have been deprecated:
+
+- `IBMDB2\DB2Exception`
+- `Mysqli\MysqliException`
+- `OCI8\OCI8Exception`
+- `PDOException`
+- `SQLSrv\SQLSrvException`
+
+A driver-level exception should be only identified as a subtype of `Driver\Exception`.
+Internal driver-level exception implementations may use `Driver\AbstractException` as the base class.
+Driver-specific exception handling has to be implemented either in the driver or based on the type of the `Driver` implementation.
+
+The `Driver\AbstractException` class has been marked internal.
+
 ## `Connection::getParams()` has been marked internal
 
 Consumers of the Connection class should not rely on connection parameters stored in the connection object. If needed, they should be obtained from a different source, e.g. application configuration.

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -4,7 +4,7 @@
 
 use ArrayIterator;
 use Doctrine\Common\Cache\Cache;
-use Doctrine\DBAL\Driver\DriverException;
+use Doctrine\DBAL\Driver\Exception;
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\ResultStatement;
@@ -297,7 +297,7 @@ public function free(): void
     /**
      * @return array<string,mixed>|false
      *
-     * @throws DriverException
+     * @throws Exception
      */
     private function doFetch()
     {

lib/Doctrine/DBAL/DBALException.php

@@ -2,7 +2,7 @@
 
 namespace Doctrine\DBAL;
 
-use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
+use Doctrine\DBAL\Driver\DriverException as DeprecatedDriverException;
 use Doctrine\DBAL\Driver\ExceptionConverterDriver;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
@@ -168,7 +168,7 @@ private static function wrapException(Driver $driver, Throwable $driverEx, strin
             return $driverEx;
         }
 
-        if ($driver instanceof ExceptionConverterDriver && $driverEx instanceof DriverExceptionInterface) {
+        if ($driver instanceof ExceptionConverterDriver && $driverEx instanceof DeprecatedDriverException) {
             return $driver->convertException($msg, $driverEx);
         }
 

lib/Doctrine/DBAL/Driver/AbstractDriverException.php

@@ -2,55 +2,11 @@
 
 namespace Doctrine\DBAL\Driver;
 
-use Exception;
-
 /**
- * Abstract base implementation of the {@link DriverException} interface.
+ * @deprecated
  *
  * @psalm-immutable
  */
-abstract class AbstractDriverException extends Exception implements DriverException
+class AbstractDriverException extends AbstractException
 {
-    /**
-     * The driver specific error code.
-     *
-     * @var int|string|null
-     */
-    private $errorCode;
-
-    /**
-     * The SQLSTATE of the driver.
-     *
-     * @var string|null
-     */
-    private $sqlState;
-
-    /**
-     * @param string          $message   The driver error message.
-     * @param string|null     $sqlState  The SQLSTATE the driver is in at the time the error occurred, if any.
-     * @param int|string|null $errorCode The driver specific error code if any.
-     */
-    public function __construct($message, $sqlState = null, $errorCode = null)
-    {
-        parent::__construct($message);
-
-        $this->errorCode = $errorCode;
-        $this->sqlState  = $sqlState;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getErrorCode()
-    {
-        return $this->errorCode;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getSQLState()
-    {
-        return $this->sqlState;
-    }
 }

lib/Doctrine/DBAL/Driver/AbstractException.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Driver;
+
+use Exception as BaseException;
+
+/**
+ * Base implementation of the {@link Exception} interface.
+ *
+ * @internal
+ *
+ * @psalm-immutable
+ */
+abstract class AbstractException extends BaseException implements DriverException
+{
+    /**
+     * The driver specific error code.
+     *
+     * @var int|string|null
+     */
+    private $errorCode;
+
+    /**
+     * The SQLSTATE of the driver.
+     *
+     * @var string|null
+     */
+    private $sqlState;
+
+    /**
+     * @param string          $message   The driver error message.
+     * @param string|null     $sqlState  The SQLSTATE the driver is in at the time the error occurred, if any.
+     * @param int|string|null $errorCode The driver specific error code if any.
+     */
+    public function __construct($message, $sqlState = null, $errorCode = null)
+    {
+        parent::__construct($message);
+
+        $this->errorCode = $errorCode;
+        $this->sqlState  = $sqlState;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getErrorCode()
+    {
+        return $this->errorCode;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getSQLState()
+    {
+        return $this->sqlState;
+    }
+}

lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php

@@ -5,7 +5,19 @@
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Driver\DriverException as DeprecatedDriverException;
+use Doctrine\DBAL\Exception\ConnectionException;
+use Doctrine\DBAL\Exception\DeadlockException;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
+use Doctrine\DBAL\Exception\InvalidFieldNameException;
+use Doctrine\DBAL\Exception\LockWaitTimeoutException;
+use Doctrine\DBAL\Exception\NonUniqueFieldNameException;
+use Doctrine\DBAL\Exception\NotNullConstraintViolationException;
+use Doctrine\DBAL\Exception\SyntaxErrorException;
+use Doctrine\DBAL\Exception\TableExistsException;
+use Doctrine\DBAL\Exception\TableNotFoundException;
+use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
 use Doctrine\DBAL\Platforms\MariaDb1027Platform;
 use Doctrine\DBAL\Platforms\MySQL57Platform;
 use Doctrine\DBAL\Platforms\MySQL80Platform;
@@ -19,7 +31,7 @@
 use function version_compare;
 
 /**
- * Abstract base implementation of the {@link Doctrine\DBAL\Driver} interface for MySQL based drivers.
+ * Abstract base implementation of the {@link Driver} interface for MySQL based drivers.
  */
 abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver, VersionAwarePlatformDriver
 {
@@ -29,44 +41,44 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
      * @link https://dev.mysql.com/doc/refman/8.0/en/client-error-reference.html
      * @link https://dev.mysql.com/doc/refman/8.0/en/server-error-reference.html
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException($message, DeprecatedDriverException $exception)
     {
         switch ($exception->getErrorCode()) {
             case '1213':
-                return new Exception\DeadlockException($message, $exception);
+                return new DeadlockException($message, $exception);
 
             case '1205':
-                return new Exception\LockWaitTimeoutException($message, $exception);
+                return new LockWaitTimeoutException($message, $exception);
 
             case '1050':
-                return new Exception\TableExistsException($message, $exception);
+                return new TableExistsException($message, $exception);
 
             case '1051':
             case '1146':
-                return new Exception\TableNotFoundException($message, $exception);
+                return new TableNotFoundException($message, $exception);
 
             case '1216':
             case '1217':
             case '1451':
             case '1452':
             case '1701':
-                return new Exception\ForeignKeyConstraintViolationException($message, $exception);
+                return new ForeignKeyConstraintViolationException($message, $exception);
 
             case '1062':
             case '1557':
             case '1569':
             case '1586':
-                return new Exception\UniqueConstraintViolationException($message, $exception);
+                return new UniqueConstraintViolationException($message, $exception);
 
             case '1054':
             case '1166':
             case '1611':
-                return new Exception\InvalidFieldNameException($message, $exception);
+                return new InvalidFieldNameException($message, $exception);
 
             case '1052':
             case '1060':
             case '1110':
-                return new Exception\NonUniqueFieldNameException($message, $exception);
+                return new NonUniqueFieldNameException($message, $exception);
 
             case '1064':
             case '1149':
@@ -80,7 +92,7 @@ public function convertException($message, DriverException $exception)
             case '1541':
             case '1554':
             case '1626':
-                return new Exception\SyntaxErrorException($message, $exception);
+                return new SyntaxErrorException($message, $exception);
 
             case '1044':
             case '1045':
@@ -94,7 +106,7 @@ public function convertException($message, DriverException $exception)
             case '1429':
             case '2002':
             case '2005':
-                return new Exception\ConnectionException($message, $exception);
+                return new ConnectionException($message, $exception);
 
             case '1048':
             case '1121':
@@ -104,10 +116,10 @@ public function convertException($message, DriverException $exception)
             case '1263':
             case '1364':
             case '1566':
-                return new Exception\NotNullConstraintViolationException($message, $exception);
+                return new NotNullConstraintViolationException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**

lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php

@@ -5,56 +5,66 @@
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\AbstractOracleDriver\EasyConnectString;
-use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Driver\DriverException as DeprecatedDriverException;
+use Doctrine\DBAL\Exception\ConnectionException;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
+use Doctrine\DBAL\Exception\InvalidFieldNameException;
+use Doctrine\DBAL\Exception\NonUniqueFieldNameException;
+use Doctrine\DBAL\Exception\NotNullConstraintViolationException;
+use Doctrine\DBAL\Exception\SyntaxErrorException;
+use Doctrine\DBAL\Exception\TableExistsException;
+use Doctrine\DBAL\Exception\TableNotFoundException;
+use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
 use Doctrine\DBAL\Platforms\OraclePlatform;
 use Doctrine\DBAL\Schema\OracleSchemaManager;
 
 /**
- * Abstract base implementation of the {@link Doctrine\DBAL\Driver} interface for Oracle based drivers.
+ * Abstract base implementation of the {@link Driver} interface for Oracle based drivers.
  */
 abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
 {
     /**
      * {@inheritdoc}
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException($message, DeprecatedDriverException $exception)
     {
         switch ($exception->getErrorCode()) {
             case '1':
             case '2299':
             case '38911':
-                return new Exception\UniqueConstraintViolationException($message, $exception);
+                return new UniqueConstraintViolationException($message, $exception);
 
             case '904':
-                return new Exception\InvalidFieldNameException($message, $exception);
+                return new InvalidFieldNameException($message, $exception);
 
             case '918':
             case '960':
-                return new Exception\NonUniqueFieldNameException($message, $exception);
+                return new NonUniqueFieldNameException($message, $exception);
 
             case '923':
-                return new Exception\SyntaxErrorException($message, $exception);
+                return new SyntaxErrorException($message, $exception);
 
             case '942':
-                return new Exception\TableNotFoundException($message, $exception);
+                return new TableNotFoundException($message, $exception);
 
             case '955':
-                return new Exception\TableExistsException($message, $exception);
+                return new TableExistsException($message, $exception);
 
             case '1017':
             case '12545':
-                return new Exception\ConnectionException($message, $exception);
+                return new ConnectionException($message, $exception);
 
             case '1400':
-                return new Exception\NotNullConstraintViolationException($message, $exception);
+                return new NotNullConstraintViolationException($message, $exception);
 
             case '2266':
             case '2291':
             case '2292':
-                return new Exception\ForeignKeyConstraintViolationException($message, $exception);
+                return new ForeignKeyConstraintViolationException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**