Merge pull request #4129 from morozov/remove-exception-converter-driver

Remove ExceptionConverterDriver

UPGRADE.md

 # Upgrade to 3.0
 
+## The `ExceptionConverterDriver` interface is removed
+
+All drivers must implement the `convertException()` method which is now part of the `Driver` interface.
+
 ## The `PingableConnection` interface is removed
 
 The functionality of pinging the server is no longer supported.

src/DBALException.php

@@ -3,7 +3,6 @@
 namespace Doctrine\DBAL;
 
 use Doctrine\DBAL\Driver\Exception as TheDriverException;
-use Doctrine\DBAL\Driver\ExceptionConverterDriver;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Types\Type;
@@ -169,7 +168,7 @@ class DBALException extends Exception
             return $driverEx;
         }
 
-        if ($driver instanceof ExceptionConverterDriver && $driverEx instanceof TheDriverException) {
+        if ($driverEx instanceof TheDriverException) {
             return $driver->convertException($msg, $driverEx);
         }
 

src/Driver.php

@@ -4,6 +4,7 @@ namespace Doctrine\DBAL;
 
 use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use Doctrine\DBAL\Driver\Exception;
+use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\AbstractSchemaManager;
 
@@ -39,4 +40,17 @@ interface Driver
      * @return AbstractSchemaManager
      */
     public function getSchemaManager(Connection $conn);
+
+    /**
+     * Converts a given driver-level exception into a DBAL-level driver exception.
+     *
+     * Implementors should use the vendor-specific error code and SQLSTATE of the exception
+     * and instantiate the most appropriate specialized {@link DriverException} subclass.
+     *
+     * @param string    $message   The exception message to use.
+     * @param Exception $exception The driver exception to convert.
+     *
+     * @return DriverException An instance of {@link DriverException} or one of its subclasses.
+     */
+    public function convertException($message, Exception $exception);
 }

src/Driver/AbstractDB2Driver.php

@@ -4,7 +4,6 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\DB2Platform;
 use Doctrine\DBAL\Schema\DB2SchemaManager;
@@ -35,7 +34,7 @@ abstract class AbstractDB2Driver implements Driver
      *
      * @return DriverException
      */
-    public function convertException($message, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         return new DriverException($message, $exception);
     }

src/Driver/AbstractMySQLDriver.php

@@ -4,7 +4,6 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\ConnectionException;
 use Doctrine\DBAL\Exception\ConnectionLost;
 use Doctrine\DBAL\Exception\DeadlockException;
@@ -32,7 +31,7 @@ use function version_compare;
 /**
  * Abstract base implementation of the {@link Driver} interface for MySQL based drivers.
  */
-abstract class AbstractMySQLDriver implements ExceptionConverterDriver, VersionAwarePlatformDriver
+abstract class AbstractMySQLDriver implements VersionAwarePlatformDriver
 {
     /**
      * {@inheritdoc}
@@ -40,7 +39,7 @@ abstract class AbstractMySQLDriver implements ExceptionConverterDriver, VersionA
      * @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, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         switch ($exception->getCode()) {
             case 1213:

src/Driver/AbstractOracleDriver.php

@@ -5,7 +5,6 @@ namespace Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\AbstractOracleDriver\EasyConnectString;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\ConnectionException;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
@@ -22,12 +21,12 @@ use Doctrine\DBAL\Schema\OracleSchemaManager;
 /**
  * Abstract base implementation of the {@link Driver} interface for Oracle based drivers.
  */
-abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
+abstract class AbstractOracleDriver implements Driver
 {
     /**
      * {@inheritdoc}
      */
-    public function convertException($message, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         switch ($exception->getCode()) {
             case 1:

src/Driver/AbstractPostgreSQLDriver.php

@@ -4,7 +4,6 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\ConnectionException;
 use Doctrine\DBAL\Exception\DeadlockException;
 use Doctrine\DBAL\Exception\DriverException;
@@ -28,14 +27,14 @@ use function version_compare;
 /**
  * Abstract base implementation of the {@link Driver} interface for PostgreSQL based drivers.
  */
-abstract class AbstractPostgreSQLDriver implements ExceptionConverterDriver, VersionAwarePlatformDriver
+abstract class AbstractPostgreSQLDriver implements VersionAwarePlatformDriver
 {
     /**
      * {@inheritdoc}
      *
      * @link http://www.postgresql.org/docs/9.4/static/errcodes-appendix.html
      */
-    public function convertException($message, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         switch ($exception->getSQLState()) {
             case '40001':

src/Driver/AbstractSQLServerDriver.php

@@ -4,7 +4,6 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\SQLServer2012Platform;
 use Doctrine\DBAL\Schema\SQLServerSchemaManager;
@@ -35,7 +34,7 @@ abstract class AbstractSQLServerDriver implements Driver
      *
      * @return DriverException
      */
-    public function convertException($message, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         return new DriverException($message, $exception);
     }

src/Driver/AbstractSQLiteDriver.php

@@ -4,7 +4,6 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
 use Doctrine\DBAL\Exception\ConnectionException;
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
@@ -25,14 +24,14 @@ use function strpos;
 /**
  * Abstract base implementation of the {@link Doctrine\DBAL\Driver} interface for SQLite based drivers.
  */
-abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
+abstract class AbstractSQLiteDriver implements Driver
 {
     /**
      * {@inheritdoc}
      *
      * @link http://www.sqlite.org/c3ref/c_abort.html
      */
-    public function convertException($message, TheDriverException $exception)
+    public function convertException($message, Exception $exception)
     {
         if (strpos($exception->getMessage(), 'database is locked') !== false) {
             return new LockWaitTimeoutException($message, $exception);

src/Driver/ExceptionConverterDriver.php

-<?php
-
-namespace Doctrine\DBAL\Driver;
-
-use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Driver\Exception as TheDriverException;
-use Doctrine\DBAL\Exception\DriverException;
-
-/**
- * Contract for a driver that is capable of converting DBAL driver exceptions into standardized DBAL driver exceptions.
- *
- * @deprecated All implementors of the {@link Driver} interface will have to implement this API.
- */
-interface ExceptionConverterDriver
-{
-    /**
-     * Converts a given DBAL driver exception into a standardized DBAL driver exception.
-     *
-     * It evaluates the vendor specific error code and SQLSTATE and transforms
-     * it into a unified {@link DriverException} subclass.
-     *
-     * @param string             $message   The DBAL exception message to use.
-     * @param TheDriverException $exception The DBAL driver exception to convert.
-     *
-     * @return DriverException An instance of one of the DriverException subclasses.
-     */
-    public function convertException($message, TheDriverException $exception);
-}

tests/Driver/AbstractDriverTest.php

@@ -5,8 +5,9 @@ namespace Doctrine\DBAL\Tests\Driver;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver;
-use Doctrine\DBAL\Driver\Exception as DriverExceptionInterface;
-use Doctrine\DBAL\Driver\ExceptionConverterDriver;
+use Doctrine\DBAL\Driver\AbstractException;
+use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\Driver\IBMDB2;
 use Doctrine\DBAL\Exception\ConnectionException;
 use Doctrine\DBAL\Exception\ConstraintViolationException;
 use Doctrine\DBAL\Exception\DatabaseObjectExistsException;
@@ -78,15 +79,18 @@ abstract class AbstractDriverTest extends TestCase
         ?string $sqlState = null,
         string $message = ''
     ): void {
-        if (! $this->driver instanceof ExceptionConverterDriver) {
-            self::markTestSkipped('This test is only intended for exception converter drivers.');
+        if ($this->driver instanceof IBMDB2\Driver) {
+            self::markTestSkipped("The IBM DB2 driver currently doesn't instantiate specialized exceptions");
         }
 
-        $driverException = $this->getMockBuilder(DriverExceptionInterface::class)
-            ->setConstructorArgs([$message, $errorCode])
-            ->getMock();
-        $driverException->method('getSQLState')
-            ->willReturn($sqlState);
+        if ($this->driver instanceof AbstractSQLServerDriver) {
+            self::markTestSkipped("The SQL Server drivers currently don't instantiate specialized exceptions");
+        }
+
+        $driverException = $this->getMockForAbstractClass(
+            AbstractException::class,
+            [$message, $sqlState, $errorCode]
+        );
 
         $dbalMessage   = 'DBAL exception message';
         $dbalException = $this->driver->convertException($dbalMessage, $driverException);

tests/Functional/ExceptionTest.php

@@ -2,7 +2,8 @@
 
 namespace Doctrine\DBAL\Tests\Functional;
 
-use Doctrine\DBAL\Driver\ExceptionConverterDriver;
+use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\Driver\IBMDB2;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\Exception;
@@ -35,11 +36,17 @@ class ExceptionTest extends FunctionalTestCase
     {
         parent::setUp();
 
-        if ($this->connection->getDriver() instanceof ExceptionConverterDriver) {
+        $driver = $this->connection->getDriver();
+
+        if ($driver instanceof IBMDB2\Driver) {
+            self::markTestSkipped("The IBM DB2 driver currently doesn't instantiate specialized exceptions");
+        }
+
+        if (! $driver instanceof AbstractSQLServerDriver) {
             return;
         }
 
-        self::markTestSkipped('Driver does not support special exception handling.');
+        self::markTestSkipped("The SQL Server drivers currently don't instantiate specialized exceptions");
     }
 
     public function testPrimaryConstraintViolationException(): void