Merge 3.2.x into 4.0.x

UPGRADE.md

@@ -8,6 +8,11 @@ awareness about deprecated code.
 
 # Upgrade to 3.2
 
+## Deprecated driver-level APIs that don't take the server version into account.
+
+The `ServerInfoAwareConnection` and `VersionAwarePlatformDriver` interfaces are deprecated. In the next major version,
+all drivers and driver connections will be required to implement the APIs aware of the server version.
+
 ## Deprecated `AbstractPlatform::getNowExpression()`.
 
 Relying on dates generated by the database is deprecated. Generate dates within the application.

psalm.xml.dist

@@ -56,8 +56,22 @@
                 -->
                 <referencedClass name="Doctrine\DBAL\Id\TableGenerator"/>
                 <referencedClass name="Doctrine\DBAL\Id\TableGeneratorSchemaVisitor"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedClass name="Doctrine\DBAL\Driver\ServerInfoAwareConnection"/>
+                <referencedClass name="Doctrine\DBAL\VersionAwarePlatformDriver"/>
             </errorLevel>
         </DeprecatedClass>
+        <DeprecatedInterface>
+            <errorLevel type="suppress">
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedClass name="Doctrine\DBAL\Driver\ServerInfoAwareConnection"/>
+                <referencedClass name="Doctrine\DBAL\VersionAwarePlatformDriver"/>
+            </errorLevel>
+        </DeprecatedInterface>
         <DeprecatedMethod>
             <errorLevel type="suppress">
                 <!--

src/Connection.php

@@ -31,6 +31,7 @@
 use function array_key_exists;
 use function assert;
 use function count;
+use function get_class;
 use function implode;
 use function is_int;
 use function is_string;
@@ -441,6 +442,13 @@ private function getServerVersion()
             }
         }
 
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pulls/4750',
+            'Not implementing the ServerInfoAwareConnection interface in %s is deprecated',
+            get_class($connection)
+        );
+
         // Unable to detect platform version.
         return null;
     }

src/Driver/ServerInfoAwareConnection.php

@@ -4,6 +4,9 @@
 
 /**
  * Contract for a connection that is able to provide information about the server it is connected to.
+ *
+ * @deprecated The methods defined in this interface will be made part of the {@link Driver} interface
+ * in the next major release.
  */
 interface ServerInfoAwareConnection extends Connection
 {

src/Portability/Connection.php

@@ -4,14 +4,16 @@
 
 use Doctrine\DBAL\Driver\Connection as ConnectionInterface;
 use Doctrine\DBAL\Driver\Result as DriverResult;
+use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
 use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use Doctrine\Deprecations\Deprecation;
+use LogicException;
 
 /**
  * Portability wrapper for a Connection.
  */
-final class Connection implements ConnectionInterface
+final class Connection implements ServerInfoAwareConnection
 {
     public const PORTABILITY_ALL           = 255;
     public const PORTABILITY_NONE          = 0;
@@ -99,4 +101,16 @@ public function rollBack()
     {
         return $this->connection->rollBack();
     }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function getServerVersion()
+    {
+        if (! $this->connection instanceof ServerInfoAwareConnection) {
+            throw new LogicException('The underlying connection is not a ServerInfoAwareConnection');
+        }
+
+        return $this->connection->getServerVersion();
+    }
 }

src/VersionAwarePlatformDriver.php

@@ -11,6 +11,8 @@
  * support the correct features and SQL syntax of each version.
  * This interface should be implemented by drivers that are capable to do this
  * distinction.
+ *
+ * @deprecated All drivers will have to be aware of the server version in the next major release.
  */
 interface VersionAwarePlatformDriver extends Driver
 {

tests/Portability/ConnectionTest.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Doctrine\DBAL\Tests\Portability;
+
+use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Portability\Connection;
+use Doctrine\DBAL\Portability\Converter;
+use PHPUnit\Framework\TestCase;
+
+class ConnectionTest extends TestCase
+{
+    public function testGetServerVersion(): void
+    {
+        $driverConnection = $this->createMock(ServerInfoAwareConnection::class);
+        $driverConnection->expects(self::once())
+            ->method('getServerVersion')
+            ->willReturn('1.2.3');
+
+        $connection = new Connection($driverConnection, new Converter(false, false, 0));
+
+        self::assertSame('1.2.3', $connection->getServerVersion());
+    }
+}