Manually merge 2.11.x into 3.0.x

UPGRADE.md

@@ -1,5 +1,17 @@
 # Upgrade to 3.0
 
+## BC BREAK: PDO-based driver classes are moved under the PDO namespace
+
+The following classes have been renamed:
+
+- `PDOMySql\Driver` → `PDO\MySQL\Driver`
+- `PDOOracle\Driver` → `PDO\OCI\Driver`
+- `PDOPgSql\Driver` → `PDO\PgSQL\Driver`
+- `PDOSqlite\Driver` → `PDO\SQLite\Driver`
+- `PDOSqlsrv\Driver` → `PDO\SQLSrv\Driver`
+- `PDOSqlsrv\Connection` → `PDO\SQLSrv\Connection`
+- `PDOSqlsrv\Statement` → `PDO\SQLSrv\Statement`
+
 ## BC BREAK: Changes schema manager instantiation.
 
 1. The `$platform` argument of all schema manager constructors is no longer optional.
@@ -307,22 +319,49 @@ Please use other database client applications for import, e.g.:
 
 # Upgrade to 2.11
 
+## PDO-related classes outside of the PDO namespace are deprecated
+
+The following outside of the PDO namespace have been deprecated in favor of their counterparts in the PDO namespace:
+
+- `PDOMySql\Driver` → `PDO\MySQL\Driver`
+- `PDOOracle\Driver` → `PDO\OCI\Driver`
+- `PDOPgSql\Driver` → `PDO\PgSQL\Driver`
+- `PDOSqlite\Driver` → `PDO\SQLite\Driver`
+- `PDOSqlsrv\Driver` → `PDO\SQLSrv\Driver`
+- `PDOSqlsrv\Connection` → `PDO\SQLSrv\Connection`
+- `PDOSqlsrv\Statement` → `PDO\SQLSrv\Statement`
+
+## 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.
+2. `DBALException::invalidPdoInstance()` as passing a PDO instance via configuration is deprecated.
+
+## `AbstractPlatform::fixSchemaElementName()` is deprecated.
+
+The method is not used anywhere except for tests.
+
 ##`ServerInfoAwareConnection::requiresQueryForServerVersion()` is deprecated.
 
 The `ServerInfoAwareConnection::requiresQueryForServerVersion()` method has been deprecated as an implementation detail which is the same for almost all supported drivers.
 
-## Statement constructors are marked internal
+## Connection and Statement constructors are marked internal
 
-The driver and wrapper statement objects can be only created by the corresponding connection objects.
+1. Driver connection objects can be only created by the corresponding drivers.
+2. Wrapper connection objects can be only created by the driver manager.
+3. The driver and wrapper connection objects can be only created by the corresponding connection objects.
+
+Additionally, the `SQLSrv\LastInsertId` class has been marked internal.
 
 ## 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.
-
 ## `DriverException::getErrorCode()` is deprecated
 
 The `DriverException::getErrorCode()` is deprecated as redundant and inconsistently supported by drivers. Use `::getCode()` or `::getSQLState()` instead.

composer.json

@@ -37,7 +37,7 @@
         "doctrine/event-manager": "^1.0"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^8.0",
+        "doctrine/coding-standard": "^8.1",
         "jetbrains/phpstorm-stubs": "^2019.1",
         "nikic/php-parser": "^4.4",
         "phpstan/phpstan": "^0.12.31",

psalm.xml

@@ -37,7 +37,7 @@
                 <!--
                     Fixing these issues requires an API change
                 -->
-                <file name="src/Driver/PDOSqlsrv/Connection.php"/>
+                <file name="src/Driver/PDO/SQLSrv/Connection.php"/>
                 <file name="src/Driver/SQLSrv/Connection.php"/>
             </errorLevel>
         </FalsableReturnStatement>
@@ -64,7 +64,7 @@
                     Requires a release of
                     https://github.com/JetBrains/phpstorm-stubs/pull/732
                 -->
-                <file name="tests/Driver/PDOPgSql/DriverTest.php" />
+                <file name="tests/Driver/PDO/PgSQL/DriverTest.php" />
             </errorLevel>
         </UndefinedConstant>
         <UndefinedClass>

src/Connection.php

@@ -148,6 +148,8 @@ class Connection implements DriverConnection
     /**
      * Initializes a new instance of the Connection class.
      *
+     * @internal The connection can be only instantiated by the driver manager.
+     *
      * @param mixed[]            $params       The connection parameters.
      * @param Driver             $driver       The driver to use.
      * @param Configuration|null $config       The configuration, optional.

src/Connections/PrimaryReadReplicaConnection.php

@@ -94,6 +94,8 @@ class PrimaryReadReplicaConnection extends Connection
     /**
      * Creates Primary Replica Connection.
      *
+     * @internal The connection can be only instantiated by the driver manager.
+     *
      * @param mixed[] $params
      *
      * @throws InvalidArgumentException

src/DBALException.php

@@ -28,6 +28,9 @@ public static function notSupported($method)
         return new self(sprintf("Operation '%s' is not supported by platform.", $method));
     }
 
+    /**
+     * @deprecated Use {@link invalidPlatformType()} instead.
+     */
     public static function invalidPlatformSpecified(): self
     {
         return new self(
@@ -80,6 +83,8 @@ public static function invalidPlatformVersionSpecified($version, $expectedFormat
     }
 
     /**
+     * @deprecated Passing a PDO instance in connection parameters is deprecated.
+     *
      * @return DBALException
      */
     public static function invalidPdoInstance()

src/Driver/IBMDB2/Connection.php

@@ -36,6 +36,8 @@ final class Connection implements ServerInfoAwareConnection
     private $conn = null;
 
     /**
+     * @internal The connection can be only instantiated by its driver.
+     *
      * @param array<string,mixed> $driverOptions
      *
      * @throws Exception

src/Driver/Mysqli/Connection.php

@@ -26,6 +26,8 @@ final class Connection implements ServerInfoAwareConnection
     private $conn;
 
     /**
+     * @internal The connection can be only instantiated by its driver.
+     *
      * @param iterable<Initializer> $preInitializers
      * @param iterable<Initializer> $postInitializers
      *

src/Driver/OCI8/Connection.php

@@ -37,6 +37,8 @@ final class Connection implements ConnectionInterface, ServerInfoAwareConnection
     /**
      * Creates a Connection to an Oracle Database using oci8 extension.
      *
+     * @internal The connection can be only instantiated by its driver.
+     *
      * @param string $username
      * @param string $password
      * @param string $db

src/Driver/PDO/Connection.php

@@ -19,6 +19,8 @@ final class Connection implements ServerInfoAwareConnection
     private $connection;
 
     /**
+     * @internal The connection can be only instantiated by its driver.
+     *
      * @param string       $dsn
      * @param string|null  $user
      * @param string|null  $password

src/Driver/PDOMySql/Driver.php → src/Driver/PDO/MySQL/Driver.php

@@ -1,14 +1,11 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOMySql;
+namespace Doctrine\DBAL\Driver\PDO\MySQL;
 
 use Doctrine\DBAL\Driver\AbstractMySQLDriver;
 use Doctrine\DBAL\Driver\PDO\Connection;
 use PDO;
 
-/**
- * PDO MySql driver.
- */
 final class Driver extends AbstractMySQLDriver
 {
     /**

src/Driver/PDOOracle/Driver.php → src/Driver/PDO/OCI/Driver.php

@@ -1,19 +1,11 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOOracle;
+namespace Doctrine\DBAL\Driver\PDO\OCI;
 
 use Doctrine\DBAL\Driver\AbstractOracleDriver;
 use Doctrine\DBAL\Driver\PDO\Connection;
 use PDO;
 
-/**
- * PDO Oracle driver.
- *
- * WARNING: This driver gives us segfaults in our testsuites on CLOB and other
- * stuff. PDO Oracle is not maintained by Oracle or anyone in the PHP community,
- * which leads us to the recommendation to use the "oci8" driver to connect
- * to Oracle instead.
- */
 final class Driver extends AbstractOracleDriver
 {
     /**

src/Driver/PDOPgSql/Driver.php → src/Driver/PDO/PgSQL/Driver.php

@@ -1,16 +1,13 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOPgSql;
+namespace Doctrine\DBAL\Driver\PDO\PgSQL;
 
 use Doctrine\DBAL\Driver\AbstractPostgreSQLDriver;
 use Doctrine\DBAL\Driver\PDO\Connection;
 use PDO;
 
 use function defined;
 
-/**
- * Driver that connects through pdo_pgsql.
- */
 final class Driver extends AbstractPostgreSQLDriver
 {
     /**

src/Driver/PDOSqlsrv/Connection.php → src/Driver/PDO/SQLSrv/Connection.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOSqlsrv;
+namespace Doctrine\DBAL\Driver\PDO\SQLSrv;
 
 use Doctrine\DBAL\Driver\PDO\Connection as PDOConnection;
 use Doctrine\DBAL\Driver\Result;

src/Driver/PDOSqlsrv/Driver.php → src/Driver/PDO/SQLSrv/Driver.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOSqlsrv;
+namespace Doctrine\DBAL\Driver\PDO\SQLSrv;
 
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver\Exception\PortWithoutHost;
@@ -11,9 +11,6 @@
 use function is_int;
 use function sprintf;
 
-/**
- * The PDO-based Sqlsrv driver.
- */
 final class Driver extends AbstractSQLServerDriver
 {
     /**

src/Driver/PDOSqlsrv/Statement.php → src/Driver/PDO/SQLSrv/Statement.php

@@ -1,16 +1,13 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOSqlsrv;
+namespace Doctrine\DBAL\Driver\PDO\SQLSrv;
 
 use Doctrine\DBAL\Driver\PDO\Statement as PDOStatement;
 use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
 use Doctrine\DBAL\ParameterType;
 use PDO;
 
-/**
- * PDO SQL Server Statement
- */
 final class Statement implements StatementInterface
 {
     /** @var PDOStatement */

src/Driver/PDOSqlite/Driver.php → src/Driver/PDO/SQLite/Driver.php

@@ -1,16 +1,13 @@
 <?php
 
-namespace Doctrine\DBAL\Driver\PDOSqlite;
+namespace Doctrine\DBAL\Driver\PDO\SQLite;
 
 use Doctrine\DBAL\Driver\AbstractSQLiteDriver;
 use Doctrine\DBAL\Driver\PDO\Connection;
 use Doctrine\DBAL\Platforms\SqlitePlatform;
 
 use function array_merge;
 
-/**
- * The PDO Sqlite driver.
- */
 final class Driver extends AbstractSQLiteDriver
 {
     /** @var mixed[] */

src/Driver/SQLSrv/Connection.php

@@ -31,6 +31,8 @@ final class Connection implements ServerInfoAwareConnection
     protected $lastInsertId;
 
     /**
+     * @internal The connection can be only instantiated by its driver.
+     *
      * @param string  $serverName
      * @param mixed[] $connectionOptions
      *

src/Driver/SQLSrv/LastInsertId.php

@@ -4,6 +4,8 @@
 
 /**
  * Last Id Data Container.
+ *
+ * @internal
  */
 final class LastInsertId
 {