Merge pull request #4159 from morozov/wrapper-apis-are-not-driver-apis

Do not implement driver-level interfaces by wrapper-level classes

UPGRADE.md

 # Upgrade to 3.0
 
+## BC BREAK: Changes in the wrapper-level API ancestry
+
+The wrapper-level `Connection` and `Statement` classes no longer implement the corresponding driver-level interfaces.
+
 ## BC BREAK: Removed DBALException factory methods
 
 The following factory methods of the DBALException class have been removed:

docs/en/reference/architecture.rst

@@ -16,11 +16,7 @@ interfaces are implemented by concrete drivers. For all PDO based
 drivers, ``PDO`` and ``PDOStatement`` are the implementations of
 these interfaces. Thus, for PDO-based drivers, a
 ``Doctrine\DBAL\Connection`` wraps a ``PDO`` instance and a
-``Doctrine\DBAL\Statement`` wraps a ``PDOStatement`` instance. Even
-more, a ``Doctrine\DBAL\Connection`` *is a*
-``Doctrine\DBAL\Driver\Connection`` and a
-``Doctrine\DBAL\Statement`` *is a*
-``Doctrine\DBAL\Driver\Statement``.
+``Doctrine\DBAL\Statement`` wraps a ``PDOStatement`` instance.
 
 What does a ``Doctrine\DBAL\Connection`` or a
 ``Doctrine\DBAL\Statement`` add to the underlying driver

src/Connection.php

@@ -41,11 +41,10 @@ use function preg_replace;
 use function sprintf;
 
 /**
- * A wrapper around a Doctrine\DBAL\Driver\Connection that adds features like
- * events, transaction isolation levels, configuration, emulated transaction nesting,
- * lazy connecting and more.
+ * A database abstraction-level connection that implements features like events, transaction isolation levels,
+ * configuration, emulated transaction nesting, lazy connecting and more.
  */
-class Connection implements DriverConnection
+class Connection
 {
     /**
      * Represents an array of ints to be expanded by Doctrine SQL parsing.
@@ -757,7 +756,10 @@ class Connection implements DriverConnection
     }
 
     /**
-     * {@inheritDoc}
+     * @param mixed      $input
+     * @param int|string $type
+     *
+     * @return mixed
      */
     public function quote($input, $type = ParameterType::STRING)
     {
@@ -905,11 +907,9 @@ class Connection implements DriverConnection
      *
      * @param string $sql The SQL statement to prepare.
      *
-     * @return Statement
-     *
      * @throws DBALException
      */
-    public function prepare(string $sql): DriverStatement
+    public function prepare(string $sql): Statement
     {
         return new Statement($sql, $this);
     }
@@ -1215,7 +1215,7 @@ class Connection implements DriverConnection
     }
 
     /**
-     * {@inheritDoc}
+     * @return bool
      */
     public function beginTransaction()
     {
@@ -1250,7 +1250,7 @@ class Connection implements DriverConnection
     }
 
     /**
-     * {@inheritDoc}
+     * @return bool
      *
      * @throws ConnectionException If the commit failed due to no active transaction or
      *                                            because the transaction was marked for rollback only.

src/Connections/PrimaryReadReplicaConnection.php

@@ -10,9 +10,9 @@ use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use Doctrine\DBAL\Driver\Exception as DriverException;
 use Doctrine\DBAL\Driver\Result;
-use Doctrine\DBAL\Driver\Statement;
 use Doctrine\DBAL\Event\ConnectionEventArgs;
 use Doctrine\DBAL\Events;
+use Doctrine\DBAL\Statement;
 use InvalidArgumentException;
 
 use function array_rand;

src/Portability/Connection.php

@@ -30,9 +30,6 @@ final class Connection implements ConnectionInterface
         $this->converter  = $converter;
     }
 
-    /**
-     * @return Statement
-     */
     public function prepare(string $sql): DriverStatement
     {
         return new Statement(

src/Statement.php

@@ -3,7 +3,6 @@
 namespace Doctrine\DBAL;
 
 use Doctrine\DBAL\Driver\Exception;
-use Doctrine\DBAL\Driver\Result as DriverResult;
 use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Types\Type;
@@ -11,10 +10,9 @@ use Doctrine\DBAL\Types\Type;
 use function is_string;
 
 /**
- * A thin wrapper around a Doctrine\DBAL\Driver\Statement that adds support
- * for logging, DBAL mapping types, etc.
+ * A database abstraction-level statement that implements support for logging, DBAL mapping types, etc.
  */
-class Statement implements DriverStatement
+class Statement
 {
     /**
      * The SQL statement.
@@ -148,7 +146,7 @@ class Statement implements DriverStatement
      *
      * @throws DBALException
      */
-    public function execute($params = null): DriverResult
+    public function execute($params = null): Result
     {
         if ($params !== null) {
             $this->params = $params;