Merge branch '4.5.x' into 5.0.x

Author: morozov

UPGRADE.md

@@ -417,6 +417,13 @@ all drivers and middleware.
 * Upgrade to MySQL 8.0 or later.
 * Upgrade to Postgres 12 or later.
 
+# Upgrade to 4.5
+
+## Deprecated `dbname` connection parameter for `oci8` and `pdo_oci` connections.
+
+Using the `dbname` connection parameter for `oci8` and `pdo_oci` connections has been deprecated. Use `servicename` or
+`sid` instead.
+
 # Upgrade to 4.4
 
 ## Deprecated using current date, time and timestamp SQL expressions as default values

ci/github/phpunit/oci8-21.xml

@@ -17,14 +17,12 @@
         <var name="db_host" value="localhost"/>
         <var name="db_user" value="doctrine"/>
         <var name="db_password" value="oracle"/>
-        <var name="db_dbname" value="XE"/>
         <var name="db_charset" value="AL32UTF8" />
 
         <var name="tmpdb_driver" value="oci8"/>
         <var name="tmpdb_host" value="localhost"/>
         <var name="tmpdb_user" value="system"/>
         <var name="tmpdb_password" value="oracle"/>
-        <var name="tmpdb_dbname" value="XE"/>
     </php>
 
     <testsuites>

ci/github/phpunit/oci8.xml

@@ -17,14 +17,12 @@
         <var name="db_host" value="localhost"/>
         <var name="db_user" value="doctrine"/>
         <var name="db_password" value="oracle"/>
-        <var name="db_dbname" value="FREE"/>
         <var name="db_charset" value="AL32UTF8" />
 
         <var name="tmpdb_driver" value="oci8"/>
         <var name="tmpdb_host" value="localhost"/>
         <var name="tmpdb_user" value="system"/>
         <var name="tmpdb_password" value="oracle"/>
-        <var name="tmpdb_dbname" value="FREE"/>
     </php>
 
     <testsuites>

ci/github/phpunit/pdo_oci-21.xml

@@ -17,14 +17,12 @@
         <var name="db_host" value="localhost"/>
         <var name="db_user" value="doctrine"/>
         <var name="db_password" value="oracle"/>
-        <var name="db_dbname" value="XE"/>
         <var name="db_charset" value="AL32UTF8" />
 
         <var name="tmpdb_driver" value="pdo_oci"/>
         <var name="tmpdb_host" value="localhost"/>
         <var name="tmpdb_user" value="system"/>
         <var name="tmpdb_password" value="oracle"/>
-        <var name="tmpdb_dbname" value="XE"/>
     </php>
 
     <testsuites>

ci/github/phpunit/pdo_oci.xml

@@ -17,14 +17,12 @@
         <var name="db_host" value="localhost"/>
         <var name="db_user" value="doctrine"/>
         <var name="db_password" value="oracle"/>
-        <var name="db_dbname" value="FREE"/>
         <var name="db_charset" value="AL32UTF8" />
 
         <var name="tmpdb_driver" value="pdo_oci"/>
         <var name="tmpdb_host" value="localhost"/>
         <var name="tmpdb_user" value="system"/>
         <var name="tmpdb_password" value="oracle"/>
-        <var name="tmpdb_dbname" value="FREE"/>
     </php>
 
     <testsuites>

docs/en/reference/configuration.rst

@@ -302,10 +302,11 @@ pdo_oci / oci8
    database.
 -  ``host`` (string): Hostname of the database to connect to.
 -  ``port`` (integer): Port of the database to connect to.
--  ``dbname`` (string): Name of the database/schema to connect to.
+-  ``dbname`` (string): Name of the database/schema to connect to. Using this parameter is deprecated.
 -  ``servicename`` (string): Optional name by which clients can
    connect to the database instance. Will be used as Oracle's
    ``SERVICE_NAME`` connection parameter if given.
+-  ``sid`` (string): Optional identifier of the database instance to connect to.
 -  ``pooled`` (boolean): Whether to enable database resident
    connection pooling.
 -  ``charset`` (string): The charset used when connecting to the

src/Driver/AbstractOracleDriver/EasyConnectString.php

@@ -4,6 +4,8 @@
 
 namespace Doctrine\DBAL\Driver\AbstractOracleDriver;
 
+use Doctrine\Deprecations\Deprecation;
+
 use function implode;
 use function is_array;
 use function sprintf;
@@ -53,12 +55,22 @@ public static function fromConnectionParameters(array $params): self
 
         if (isset($params['dbname'])) {
             $connectData['SID'] = $params['dbname'];
+
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/7239',
+                'Using the "dbname" parameter is deprecated. Use "servicename" or "sid" instead.',
+            );
         }
 
         if (isset($params['servicename'])) {
             $connectData['SERVICE_NAME'] = $params['servicename'];
         }
 
+        if (isset($params['sid'])) {
+            $connectData['SID'] = $params['sid'];
+        }
+
         if (isset($params['instancename'])) {
             $connectData['INSTANCE_NAME'] = $params['instancename'];
         }

src/DriverManager.php

@@ -62,6 +62,7 @@
  *     replica?: array<OverrideParams>,
  *     serverVersion?: string,
  *     sessionMode?: int,
+ *     sid?: string,
  *     user?: non-empty-string,
  *     wrapperClass?: class-string<Connection>,
  *     unix_socket?: string,

tests/Driver/AbstractOracleDriver/EasyConnectStringTest.php

@@ -5,11 +5,14 @@
 namespace Doctrine\DBAL\Tests\Driver\AbstractOracleDriver;
 
 use Doctrine\DBAL\Driver\AbstractOracleDriver\EasyConnectString;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 
 class EasyConnectStringTest extends TestCase
 {
+    use VerifyDeprecations;
+
     /** @param mixed[] $params */
     #[DataProvider('connectionParametersProvider')]
     public function testFromConnectionParameters(array $params, string $expected): void
@@ -70,4 +73,49 @@ public static function connectionParametersProvider(): iterable
             ],
         ];
     }
+
+    /** @param array<string, mixed> $parameters */
+    #[DataProvider('getConnectionParameters')]
+    public function testParameterDeprecation(
+        array $parameters,
+        string $expectedConnectString,
+        bool $expectDeprecation,
+    ): void {
+        if ($expectDeprecation) {
+            $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/7239');
+        } else {
+            $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/7239');
+        }
+
+        $string = EasyConnectString::fromConnectionParameters($parameters);
+
+        self::assertSame($expectedConnectString, (string) $string);
+    }
+
+    /** @return iterable<string, array{array<string, mixed>, string, bool}> */
+    public static function getConnectionParameters(): iterable
+    {
+        $sidString = '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))'
+            . '(CONNECT_DATA=(SID=BILLING)))';
+
+        yield 'dbname' => [
+            [
+                'host' => 'localhost',
+                'port' => 1521,
+                'dbname' => 'BILLING',
+            ],
+            $sidString,
+            true,
+        ];
+
+        yield 'sid' => [
+            [
+                'host' => 'localhost',
+                'port' => 1521,
+                'sid' => 'BILLING',
+            ],
+            $sidString,
+            false,
+        ];
+    }
 }