From 3cedf31e9e4b8a531aea25cdee3846772a10f34e Mon Sep 17 00:00:00 2001 From: Sergei Morozov Date: Mon, 26 Sep 2022 17:40:56 -0700 Subject: [PATCH] Deprecate driver name aliases --- UPGRADE.md | 4 ++++ docs/en/reference/configuration.rst | 32 +++++++++-------------------- src/DriverManager.php | 25 ++++++++++++++++++---- 3 files changed, 35 insertions(+), 26 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 4d9e32c4d28..c5dfdbddb07 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -8,6 +8,10 @@ awareness about deprecated code. # Upgrade to 3.5 +## Deprecated driver name aliases. + +Relying on driver name aliases in connection parameters has been deprecated. Use the actual driver names instead. + ## Deprecated "unique" and "check" column properties. The "unique" and "check" column properties have been deprecated. Use unique constraints to define unique columns. diff --git a/docs/en/reference/configuration.rst b/docs/en/reference/configuration.rst index 2da29a1a781..69a3102e851 100644 --- a/docs/en/reference/configuration.rst +++ b/docs/en/reference/configuration.rst @@ -49,26 +49,14 @@ The path after the authority part represents the name of the database, sans the leading slash. Any query parameters are used as additional connection parameters. -The scheme names representing the drivers are either the regular -driver names (see below) with any underscores in their name replaced -with a hyphen (to make them legal in URL scheme names), or one of the -following simplified driver names that serve as aliases: - -- ``db2``: alias for ``ibm_db2`` -- ``mssql``: alias for ``pdo_sqlsrv`` -- ``mysql``/``mysql2``: alias for ``pdo_mysql`` -- ``pgsql``/``postgres``/``postgresql``: alias for ``pdo_pgsql`` -- ``sqlite``/``sqlite3``: alias for ``pdo_sqlite`` - -For example, to connect to a "foo" MySQL DB using the ``pdo_mysql`` +The scheme names representing the drivers are the driver names +with any underscores in their name replaced with a hyphen +(to make them legal in URL scheme names). + +For example, to connect to a "foo" MySQL database using the ``pdo_mysql`` driver on localhost port 4486 with the "charset" option set to ``utf8mb4``, you would use the following URL:: - mysql://localhost:4486/foo?charset=utf8mb4 - -This is identical to the following connection string using the -full driver name:: - pdo-mysql://localhost:4486/foo?charset=utf8mb4 In the example above, mind the dashes instead of the @@ -79,28 +67,28 @@ URL is obviously irrelevant and thus can be omitted. The path part of the URL is, like for all other drivers, stripped of its leading slash, resulting in a relative file name for the database:: - sqlite:///somedb.sqlite + pdo-sqlite:///somedb.sqlite This would access ``somedb.sqlite`` in the current working directory and is identical to the following:: - sqlite://ignored:ignored@ignored:1234/somedb.sqlite + pdo-sqlite://ignored:ignored@ignored:1234/somedb.sqlite To specify an absolute file path, e.g. ``/usr/local/var/db.sqlite``, simply use that as the database name, which results in two leading slashes for the path part of the URL, and four slashes in total after the URL scheme name and its following colon:: - sqlite:////usr/local/var/db.sqlite + pdo-sqlite:////usr/local/var/db.sqlite Which is, again, identical to supplying ignored user/pass/authority:: - sqlite://notused:inthis@case//usr/local/var/db.sqlite + pdo-sqlite://notused:inthis@case//usr/local/var/db.sqlite To connect to an in-memory SQLite instance, use ``:memory:`` as the database name:: - sqlite:///:memory: + pdo-sqlite:///:memory: .. note:: diff --git a/src/DriverManager.php b/src/DriverManager.php index 14d09878bfa..a1a2a2185b8 100644 --- a/src/DriverManager.php +++ b/src/DriverManager.php @@ -8,6 +8,7 @@ use Doctrine\DBAL\Driver\OCI8; use Doctrine\DBAL\Driver\PDO; use Doctrine\DBAL\Driver\SQLSrv; +use Doctrine\Deprecations\Deprecation; use function array_keys; use function array_merge; @@ -92,6 +93,8 @@ final class DriverManager /** * List of URL schemes from a database URL and their mappings to driver. * + * @deprecated Use actual driver names instead. + * * @var string[] */ private static array $driverSchemeAliases = [ @@ -451,11 +454,25 @@ private static function parseDatabaseUrlScheme(?string $scheme, array $params): // URL schemes must not contain underscores, but dashes are ok $driver = str_replace('-', '_', $scheme); - // The requested driver from the URL scheme takes precedence over the - // default driver from the connection parameters. If the driver is - // an alias (e.g. "postgres"), map it to the actual name ("pdo-pgsql"). + // If the driver is an alias (e.g. "postgres"), map it to the actual name ("pdo-pgsql"). // Otherwise, let checkParams decide later if the driver exists. - $params['driver'] = self::$driverSchemeAliases[$driver] ?? $driver; + if (isset(self::$driverSchemeAliases[$driver])) { + $actualDriver = self::$driverSchemeAliases[$driver]; + + Deprecation::trigger( + 'doctrine/dbal', + 'https://github.com/doctrine/dbal/pull/5697', + 'Relying on driver name aliases is deprecated. Use %s instead of %s.', + str_replace('_', '-', $actualDriver), + $driver, + ); + + $driver = $actualDriver; + } + + // The requested driver from the URL scheme takes precedence over the + // default driver from the connection parameters. + $params['driver'] = $driver; return $params; }