Merge pull request #5699 from morozov/deprecate-connection-platform

Deprecate platform parameter of wrapper Connection

Author: morozov

UPGRADE.md

@@ -8,6 +8,11 @@ awareness about deprecated code.
 
 # Upgrade to 3.5
 
+## Deprecated the "platform" parameter of the wrapper `Connection`.
+
+The "platform" parameter of the wrapper `Connection` has been deprecated. Use a driver middleware that would instantiate
+the platform instead.
+
 ## Deprecated driver name aliases.
 
 Relying on driver name aliases in connection parameters has been deprecated. Use the actual driver names instead.

docs/en/reference/configuration.rst

@@ -278,45 +278,15 @@ Automatic platform version detection
 
 Doctrine ships with different database platform implementations for some vendors
 to support version specific features, dialect and behaviour.
-As of Doctrine DBAL 2.5 the appropriate platform implementation for the underlying
-database server version can be detected at runtime automatically for nearly all drivers.
-Before 2.5 you had to configure Doctrine to use a certain platform implementation
-explicitly with the ``platform`` connection parameter (see section below).
-Otherwise Doctrine always used a default platform implementation. For example if
-your application was backed by a SQL Server 2012 database, Doctrine would still use
-the SQL Server 2008 platform implementation as it is the default, unless you told
-Doctrine explicitly to use the SQL Server 2012 implementation.
-
-The following drivers support automatic database platform detection out of the box
-without any extra configuration required:
-
--  ``pdo_mysql``
--  ``mysqli``
--  ``pdo_pgsql``
--  ``pdo_sqlsrv``
--  ``sqlsrv``
-
-Some drivers cannot provide the version of the underlying database server without
-having to query for it explicitly.
-
-If you still want to tell Doctrine which database server version you are using in
-order to choose the appropriate platform implementation, you can pass the
-``serverVersion`` option with a vendor specific version string that matches the
-database server version you are using.
-You can also pass this option if you want to disable automatic database platform
-detection for a driver that natively supports it and choose the platform version
-implementation explicitly.
 
-If you are running a MariaDB database, you should prefix the ``serverVersion``
-with ``mariadb-`` (ex: ``mariadb-10.2.12``).
+The drivers will automatically detect the platform version and instantiate
+the corresponding platform class.
 
-Custom Platform
-~~~~~~~~~~~~~~~
+You can also pass the ``serverVersion`` option if you want to disable automatic
+database platform detection and choose the platform version implementation explicitly.
 
-Each built-in driver uses a default implementation of
-``Doctrine\DBAL\Platforms\AbstractPlatform``. If you wish to use a
-customized or custom implementation, you can pass a precreated
-instance in the ``platform`` option.
+If you are running a MariaDB database, you should prefix the ``serverVersion``
+with ``mariadb-`` (ex: ``mariadb-10.2.12``).
 
 Custom Driver Options
 ~~~~~~~~~~~~~~~~~~~~~

src/Connection.php

@@ -184,6 +184,13 @@ public function __construct(
                 throw Exception::invalidPlatformType($params['platform']);
             }
 
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/5699',
+                'The "platform" connection parameter is deprecated.'
+                    . ' Use a driver middleware that would instantiate the platform instead.',
+            );
+
             $this->platform = $params['platform'];
             $this->platform->setEventManager($this->_eventManager);
         }