Replace forward-compatible ResultStatement interfaces with Result

UPGRADE.md

@@ -1,13 +1,22 @@
 # Upgrade to 2.11
 
+## Deprecated `ArrayStatement` and `ResultCacheStatement` classes.
+
+The `ArrayStatement` and `ResultCacheStatement` classes are deprecated. In a future major release they will be renamed and marked internal as implementation details of the caching layer.
+
+## Deprecated `ResultStatement` interface
+
+1. The `ResultStatement` interface is deprecated. Use the `Driver\Result` and `Abstraction\Result` interfaces instead.
+2. `ResultStatement::closeCursor()` is deprecated in favor of `Result::free()`.
+
 ## Deprecated `FetchMode` and the corresponding methods
 
 1. The `FetchMode` class and the `setFetchMode()` method of the `Connection` and `Statement` interfaces are deprecated.
-2. The `Statement::fetch()` method is deprecated in favor of `fetchNumeric()`, `fetchAssociative()` and `fetchOne()`.
-3. The `Statement::fetchAll()` method is deprecated in favor of `fetchAllNumeric()`, `fetchAllAssociative()` and `fetchFirstColumn()`.
-4. The `Statement::fetchColumn()` method is deprecated in favor of `fetchOne()`.
+2. The `Statement::fetch()` method is deprecated in favor of `Result::fetchNumeric()`, `::fetchAssociative()` and `::fetchOne()`.
+3. The `Statement::fetchAll()` method is deprecated in favor of `Result::fetchAllNumeric()`, `::fetchAllAssociative()` and `::fetchFirstColumn()`.
+4. The `Statement::fetchColumn()` method is deprecated in favor of `Result::fetchOne()`.
 5. The `Connection::fetchArray()` and `fetchAssoc()` method are deprecated in favor of `fetchNumeric()` and `fetchAssociative()` respectively.
-6. The `StatementIterator` class and the usage of a `Statement` object as `Traversable` is deprecated in favor of `iterateNumeric()`, `iterateAssociative()` and `iterateColumn()`.
+6. The `StatementIterator` class and the usage of a `Statement` object as `Traversable` is deprecated in favor of `Result::iterateNumeric()`, `::iterateAssociative()` and `::iterateColumn()`.
 7. Fetching data in mixed mode (`FetchMode::MIXED`) is deprecated.
 
 ## Deprecated `Connection::project()`

lib/Doctrine/DBAL/ForwardCompatibility/ResultStatement.php → lib/Doctrine/DBAL/Abstraction/Result.php

@@ -2,16 +2,17 @@
 
 declare(strict_types=1);
 
-namespace Doctrine\DBAL\ForwardCompatibility;
+namespace Doctrine\DBAL\Abstraction;
 
 use Doctrine\DBAL\DBALException;
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as BaseResultStatement;
+use Doctrine\DBAL\Driver\Result as DriverResult;
 use Traversable;
 
 /**
- * Forward compatibility extension for the DBAL ResultStatement interface.
+ * Abstraction-level result statement execution result. Provides additional methods on top
+ * of the driver-level interface.
  */
-interface ResultStatement extends BaseResultStatement
+interface Result extends DriverResult
 {
     /**
      * Returns an iterator over the result set rows represented as numeric arrays.

lib/Doctrine/DBAL/Cache/ArrayStatement.php

@@ -4,9 +4,9 @@
 
 use ArrayIterator;
 use Doctrine\DBAL\Driver\FetchUtils;
+use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\FetchMode;
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as ForwardCompatibleResultStatement;
 use InvalidArgumentException;
 use IteratorAggregate;
 use PDO;
@@ -16,7 +16,10 @@
 use function count;
 use function reset;
 
-class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
+/**
+ * @deprecated
+ */
+class ArrayStatement implements IteratorAggregate, ResultStatement, Result
 {
     /** @var mixed[] */
     private $data;
@@ -45,14 +48,24 @@ public function __construct(array $data)
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        unset($this->data);
+        $this->free();
 
         return true;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function rowCount()
+    {
+        return count($this->data);
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -210,6 +223,11 @@ public function fetchFirstColumn(): array
         return FetchUtils::fetchFirstColumn($this);
     }
 
+    public function free(): void
+    {
+        $this->data = [];
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -6,10 +6,10 @@
 use Doctrine\Common\Cache\Cache;
 use Doctrine\DBAL\Driver\DriverException;
 use Doctrine\DBAL\Driver\FetchUtils;
+use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\Statement;
 use Doctrine\DBAL\FetchMode;
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as ForwardCompatibleResultStatement;
 use InvalidArgumentException;
 use IteratorAggregate;
 use PDO;
@@ -32,8 +32,10 @@
  *
  * Also you have to realize that the cache will load the whole result into memory at once to ensure 2.
  * This means that the memory usage for cached results might increase by using this feature.
+ *
+ * @deprecated
  */
-class ResultCacheStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
+class ResultCacheStatement implements IteratorAggregate, ResultStatement, Result
 {
     /** @var Cache */
     private $resultCache;
@@ -72,12 +74,12 @@ public function __construct(ResultStatement $stmt, Cache $resultCache, $cacheKey
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        $this->statement->closeCursor();
-
-        $this->data = null;
+        $this->free();
 
         return true;
     }
@@ -234,7 +236,7 @@ public function fetchOne()
      */
     public function fetchAllNumeric(): array
     {
-        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+        if ($this->statement instanceof Result) {
             $data = $this->statement->fetchAllAssociative();
         } else {
             $data = $this->statement->fetchAll(FetchMode::ASSOCIATIVE);
@@ -250,7 +252,7 @@ public function fetchAllNumeric(): array
      */
     public function fetchAllAssociative(): array
     {
-        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+        if ($this->statement instanceof Result) {
             $data = $this->statement->fetchAllAssociative();
         } else {
             $data = $this->statement->fetchAll(FetchMode::ASSOCIATIVE);
@@ -287,6 +289,11 @@ public function rowCount()
         return $this->statement->rowCount();
     }
 
+    public function free(): void
+    {
+        $this->data = null;
+    }
+
     /**
      * @return array<string,mixed>|false
      *
@@ -298,7 +305,7 @@ private function doFetch()
             $this->data = [];
         }
 
-        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+        if ($this->statement instanceof Result) {
             $row = $this->statement->fetchAssociative();
         } else {
             $row = $this->statement->fetch(FetchMode::ASSOCIATIVE);

lib/Doctrine/DBAL/Connection.php

@@ -4,6 +4,7 @@
 
 use Closure;
 use Doctrine\Common\EventManager;
+use Doctrine\DBAL\Abstraction\Result;
 use Doctrine\DBAL\Cache\ArrayStatement;
 use Doctrine\DBAL\Cache\CacheException;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
@@ -14,7 +15,6 @@
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
 use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\Exception\InvalidArgumentException;
-use Doctrine\DBAL\ForwardCompatibility\ResultStatement as ForwardCompatibleResultStatement;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
 use Doctrine\DBAL\Query\QueryBuilder;
@@ -616,7 +616,7 @@ public function fetchAssociative(string $query, array $params = [], array $types
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchAssociative();
             }
 
@@ -643,7 +643,7 @@ public function fetchNumeric(string $query, array $params = [], array $types = [
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchNumeric();
             }
 
@@ -670,7 +670,7 @@ public function fetchOne(string $query, array $params = [], array $types = [])
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchOne();
             }
 
@@ -956,7 +956,7 @@ public function fetchAllNumeric(string $query, array $params = [], array $types
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchAllNumeric();
             }
 
@@ -982,7 +982,7 @@ public function fetchAllAssociative(string $query, array $params = [], array $ty
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchAllAssociative();
             }
 
@@ -1008,7 +1008,7 @@ public function fetchFirstColumn(string $query, array $params = [], array $types
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 return $stmt->fetchFirstColumn();
             }
 
@@ -1034,7 +1034,7 @@ public function iterateNumeric(string $query, array $params = [], array $types =
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 yield from $stmt->iterateNumeric();
             } else {
                 while (($row = $stmt->fetch(FetchMode::NUMERIC)) !== false) {
@@ -1062,7 +1062,7 @@ public function iterateAssociative(string $query, array $params = [], array $typ
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 yield from $stmt->iterateAssociative();
             } else {
                 while (($row = $stmt->fetch(FetchMode::ASSOCIATIVE)) !== false) {
@@ -1090,7 +1090,7 @@ public function iterateColumn(string $query, array $params = [], array $types =
         try {
             $stmt = $this->executeQuery($query, $params, $types);
 
-            if ($stmt instanceof ForwardCompatibleResultStatement) {
+            if ($stmt instanceof Result) {
                 yield from $stmt->iterateColumn();
             } else {
                 while (($value = $stmt->fetch(FetchMode::COLUMN)) !== false) {

lib/Doctrine/DBAL/Driver/FetchUtils.php

@@ -4,8 +4,6 @@
 
 namespace Doctrine\DBAL\Driver;
 
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement;
-
 /**
  * @internal
  */
@@ -16,9 +14,9 @@ final class FetchUtils
      *
      * @throws DriverException
      */
-    public static function fetchOne(ResultStatement $stmt)
+    public static function fetchOne(Result $result)
     {
-        $row = $stmt->fetchNumeric();
+        $row = $result->fetchNumeric();
 
         if ($row === false) {
             return false;
@@ -32,11 +30,11 @@ public static function fetchOne(ResultStatement $stmt)
      *
      * @throws DriverException
      */
-    public static function fetchAllNumeric(ResultStatement $stmt): array
+    public static function fetchAllNumeric(Result $result): array
     {
         $rows = [];
 
-        while (($row = $stmt->fetchNumeric()) !== false) {
+        while (($row = $result->fetchNumeric()) !== false) {
             $rows[] = $row;
         }
 
@@ -48,11 +46,11 @@ public static function fetchAllNumeric(ResultStatement $stmt): array
      *
      * @throws DriverException
      */
-    public static function fetchAllAssociative(ResultStatement $stmt): array
+    public static function fetchAllAssociative(Result $result): array
     {
         $rows = [];
 
-        while (($row = $stmt->fetchAssociative()) !== false) {
+        while (($row = $result->fetchAssociative()) !== false) {
             $rows[] = $row;
         }
 
@@ -64,11 +62,11 @@ public static function fetchAllAssociative(ResultStatement $stmt): array
      *
      * @throws DriverException
      */
-    public static function fetchFirstColumn(ResultStatement $stmt): array
+    public static function fetchFirstColumn(Result $result): array
     {
         $rows = [];
 
-        while (($row = $stmt->fetchOne()) !== false) {
+        while (($row = $result->fetchOne()) !== false) {
             $rows[] = $row;
         }
 

lib/Doctrine/DBAL/Driver/IBMDB2/DB2Statement.php

@@ -3,10 +3,10 @@
 namespace Doctrine\DBAL\Driver\IBMDB2;
 
 use Doctrine\DBAL\Driver\FetchUtils;
+use Doctrine\DBAL\Driver\Result;
 use Doctrine\DBAL\Driver\Statement;
 use Doctrine\DBAL\Driver\StatementIterator;
 use Doctrine\DBAL\FetchMode;
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as ForwardCompatibleResultStatement;
 use Doctrine\DBAL\ParameterType;
 use IteratorAggregate;
 use PDO;
@@ -50,7 +50,7 @@
 use const DB2_PARAM_FILE;
 use const DB2_PARAM_IN;
 
-class DB2Statement implements IteratorAggregate, Statement, ForwardCompatibleResultStatement
+class DB2Statement implements IteratorAggregate, Statement, Result
 {
     /** @var resource */
     private $stmt;
@@ -147,6 +147,8 @@ private function bind($position, &$variable, int $parameterType, int $dataType):
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
@@ -426,6 +428,15 @@ public function rowCount()
         return @db2_num_rows($this->stmt) ? : 0;
     }
 
+    public function free(): void
+    {
+        $this->bindParam = [];
+
+        db2_free_result($this->stmt);
+
+        $this->result = false;
+    }
+
     /**
      * Casts a stdClass object to the given class name mapping its' properties.
      *