Merge pull request #4137 from morozov/deprecate-driver-exception-conversion-apis

Deprecate driver exception conversion APIs

UPGRADE.md

 # Upgrade to 2.11
 
+## Deprecations in driver-level exception handling
+
+1. The `ExceptionConverterDriver` interface and the usage of the `convertException()` method on the `Driver` objects are deprecated.
+2. The `driverException()` and `driverExceptionDuringQuery()` factory methods of the `DBALException` class are deprecated.
+3. Relying on the wrapper layer handling non-driver exceptions is deprecated.
+
 ## `DBALException` factory method deprecations
 
 1. `DBALException::invalidPlatformType()` is deprecated as unused as of v2.7.0.
@@ -21,10 +27,6 @@ The driver and wrapper statement objects can be only created by the correspondin
 
 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.
-
 ## `DriverException::getErrorCode()` is deprecated
 
 The `DriverException::getErrorCode()` is deprecated as redundant and inconsistently supported by drivers. Use `::getCode()` or `::getSQLState()` instead.

lib/Doctrine/DBAL/DBALException.php

@@ -139,6 +139,8 @@ class DBALException extends Exception
     }
 
     /**
+     * @deprecated
+     *
      * @param string  $sql
      * @param mixed[] $params
      *
@@ -157,6 +159,8 @@ class DBALException extends Exception
     }
 
     /**
+     * @deprecated
+     *
      * @return self
      */
     public static function driverException(Driver $driver, Throwable $driverEx)

lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php

@@ -39,6 +39,8 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
     /**
      * {@inheritdoc}
      *
+     * @deprecated
+     *
      * @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
      */

lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php

@@ -26,6 +26,8 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
 {
     /**
      * {@inheritdoc}
+     *
+     * @deprecated
      */
     public function convertException($message, DeprecatedDriverException $exception)
     {

lib/Doctrine/DBAL/Driver/AbstractPostgreSQLDriver.php

@@ -38,6 +38,8 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
     /**
      * {@inheritdoc}
      *
+     * @deprecated
+     *
      * @link http://www.postgresql.org/docs/9.3/static/errcodes-appendix.html
      */
     public function convertException($message, DeprecatedDriverException $exception)

lib/Doctrine/DBAL/Driver/AbstractSQLAnywhereDriver.php

@@ -37,6 +37,8 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
     /**
      * {@inheritdoc}
      *
+     * @deprecated
+     *
      * @link http://dcx.sybase.com/index.html#sa160/en/saerrors/sqlerror.html
      */
     public function convertException($message, DeprecatedDriverException $exception)

lib/Doctrine/DBAL/Driver/AbstractSQLiteDriver.php

@@ -30,6 +30,8 @@ abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      *
+     * @deprecated
+     *
      * @link http://www.sqlite.org/c3ref/c_abort.html
      */
     public function convertException($message, DeprecatedDriverException $exception)

lib/Doctrine/DBAL/Driver/ExceptionConverterDriver.php

@@ -2,14 +2,13 @@
 
 namespace Doctrine\DBAL\Driver;
 
-use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\DriverException 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.
+ * @deprecated
  */
 interface ExceptionConverterDriver
 {
@@ -19,6 +18,8 @@ interface ExceptionConverterDriver
      * It evaluates the vendor specific error code and SQLSTATE and transforms
      * it into a unified {@link DriverException} subclass.
      *
+     * @deprecated
+     *
      * @param string             $message   The DBAL exception message to use.
      * @param TheDriverException $exception The DBAL driver exception to convert.
      *