Deprecate "service" connection parameter

Author: morozov

UPGRADE.md

@@ -6,6 +6,13 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 4.4
+
+## Deprecated `service` connection parameter for `oci8` and `pdo_oci` connections.
+
+Using the `service` connection parameter to indicate that the value of the `dbname` parameter is the service name has
+been  deprecated. Use the `servicename` parameter instead.
+
 # Upgrade to 4.3
 
 ## Deprecated support for MariaDB 10.5

docs/en/reference/configuration.rst

@@ -303,12 +303,11 @@ pdo_oci / oci8
 -  ``dbname`` (string): Name of the database/schema to connect to.
 -  ``servicename`` (string): Optional name by which clients can
    connect to the database instance. Will be used as Oracle's
-   ``SID`` connection parameter if given and defaults to Doctrine's
-   ``dbname`` connection parameter value.
+   ``SERVICE_NAME`` connection parameter if given.
 -  ``service`` (boolean): Whether to use Oracle's ``SERVICE_NAME``
    connection parameter in favour of ``SID`` when connecting. The
    value for this will be read from Doctrine's ``servicename`` if
-   given, ``dbname`` otherwise.
+   given, ``dbname`` otherwise. Using this parameter is deprecated.
 -  ``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;
@@ -51,10 +53,19 @@ public static function fromConnectionParameters(array $params): self
 
         $connectData = [];
 
+        if (isset($params['service'])) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/pull/7042',
+                'Using the "service" parameter to indicate that the value of the "dbname" parameter is the'
+                    . ' service name is deprecated. Use the "servicename" parameter instead.',
+            );
+        }
+
         if (isset($params['servicename']) || isset($params['dbname'])) {
             $serviceKey = 'SID';
 
-            if (isset($params['service'])) {
+            if (isset($params['service']) || isset($params['servicename'])) {
                 $serviceKey = 'SERVICE_NAME';
             }
 

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
@@ -71,4 +74,50 @@ 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/7042');
+        } else {
+            $this->expectNoDeprecationWithIdentifier('https://github.com/doctrine/dbal/pull/7042');
+        }
+
+        $string = EasyConnectString::fromConnectionParameters($parameters);
+
+        self::assertSame($expectedConnectString, (string) $string);
+    }
+
+    /** @return iterable<string, array{array<string, mixed>, string, bool}> */
+    public static function getConnectionParameters(): iterable
+    {
+        $serviceNameString = '(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))'
+            . '(CONNECT_DATA=(SERVICE_NAME=BILLING)))';
+
+        yield 'dbname-and-service' => [
+            [
+                'host' => 'localhost',
+                'port' => 1521,
+                'dbname' => 'BILLING',
+                'service' => true,
+            ],
+            $serviceNameString,
+            true,
+        ];
+
+        yield 'servicename' => [
+            [
+                'host' => 'localhost',
+                'port' => 1521,
+                'servicename' => 'BILLING',
+            ],
+            $serviceNameString,
+            false,
+        ];
+    }
 }