Deprecate ResultStatement::closeCursor() in favor of Result::free()

UPGRADE.md

@@ -2,7 +2,8 @@
 
 ## Deprecated `ResultStatement` interface
 
-The `ResultStatement` interface is deprecated. Use the `Driver\Result` and `Abstraction\Result` interfaces instead.
+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
 

lib/Doctrine/DBAL/Cache/ArrayStatement.php

@@ -45,10 +45,12 @@ class ArrayStatement implements IteratorAggregate, ResultStatement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        $this->data = [];
+        $this->free();
 
         return true;
     }
@@ -218,6 +220,11 @@ class ArrayStatement implements IteratorAggregate, ResultStatement, Result
         return FetchUtils::fetchFirstColumn($this);
     }
 
+    public function free(): void
+    {
+        $this->data = [];
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -72,12 +72,12 @@ class ResultCacheStatement implements IteratorAggregate, ResultStatement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        $this->statement->closeCursor();
-
-        $this->data = null;
+        $this->free();
 
         return true;
     }
@@ -287,6 +287,11 @@ class ResultCacheStatement implements IteratorAggregate, ResultStatement, Result
         return $this->statement->rowCount();
     }
 
+    public function free(): void
+    {
+        $this->data = null;
+    }
+
     /**
      * @return array<string,mixed>|false
      *

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

@@ -147,6 +147,8 @@ class DB2Statement implements IteratorAggregate, Statement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
@@ -426,6 +428,15 @@ class DB2Statement implements IteratorAggregate, Statement, Result
         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.
      *

lib/Doctrine/DBAL/Driver/Mysqli/MysqliStatement.php

@@ -498,11 +498,12 @@ class MysqliStatement implements IteratorAggregate, Statement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        $this->_stmt->free_result();
-        $this->result = false;
+        $this->free();
 
         return true;
     }
@@ -527,6 +528,12 @@ class MysqliStatement implements IteratorAggregate, Statement, Result
         return $this->_stmt->field_count;
     }
 
+    public function free(): void
+    {
+        $this->_stmt->free_result();
+        $this->result = false;
+    }
+
     /**
      * {@inheritdoc}
      *

lib/Doctrine/DBAL/Driver/OCI8/OCI8Statement.php

@@ -331,17 +331,12 @@ class OCI8Statement implements IteratorAggregate, Statement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        // not having the result means there's nothing to close
-        if (! $this->result) {
-            return true;
-        }
-
-        oci_cancel($this->_sth);
-
-        $this->result = false;
+        $this->free();
 
         return true;
     }
@@ -601,6 +596,18 @@ class OCI8Statement implements IteratorAggregate, Statement, Result
         return $this->doFetchAll(OCI_NUM, OCI_FETCHSTATEMENT_BY_COLUMN)[0];
     }
 
+    public function free(): void
+    {
+        // not having the result means there's nothing to close
+        if (! $this->result) {
+            return;
+        }
+
+        oci_cancel($this->_sth);
+
+        $this->result = false;
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Driver/PDOStatement.php

@@ -110,6 +110,8 @@ class PDOStatement extends \PDOStatement implements Statement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
@@ -249,6 +251,11 @@ class PDOStatement extends \PDOStatement implements Statement, Result
         return $this->fetchAll(PDO::FETCH_COLUMN);
     }
 
+    public function free(): void
+    {
+        parent::closeCursor();
+    }
+
     /**
      * Converts DBAL parameter type to PDO parameter type
      *

lib/Doctrine/DBAL/Driver/Result.php

@@ -83,9 +83,7 @@ interface Result
     public function columnCount();
 
     /**
-     * Closes the cursor, enabling the statement to be executed again.
-     *
-     * @return bool TRUE on success or FALSE on failure.
+     * Discards the non-fetched portion of the result, enabling the originating statement to be executed again.
      */
-    public function closeCursor();
+    public function free(): void;
 }

lib/Doctrine/DBAL/Driver/ResultStatement.php

@@ -13,6 +13,8 @@ interface ResultStatement extends Traversable
     /**
      * Closes the cursor, enabling the statement to be executed again.
      *
+     * @deprecated Use Result::free() instead.
+     *
      * @return bool TRUE on success or FALSE on failure.
      */
     public function closeCursor();

lib/Doctrine/DBAL/Driver/SQLAnywhere/SQLAnywhereStatement.php

@@ -136,6 +136,8 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement, Result
     /**
      * {@inheritdoc}
      *
+     * @deprecated Use free() instead.
+     *
      * @throws SQLAnywhereException
      */
     public function closeCursor()
@@ -388,6 +390,11 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement, Result
         return sasql_stmt_affected_rows($this->stmt);
     }
 
+    public function free(): void
+    {
+        sasql_stmt_reset($this->stmt);
+    }
+
     /**
      * {@inheritdoc}
      *

lib/Doctrine/DBAL/Driver/SQLSrv/SQLSrvStatement.php

@@ -186,22 +186,12 @@ class SQLSrvStatement implements IteratorAggregate, Statement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
-        // not having the result means there's nothing to close
-        if ($this->stmt === null || ! $this->result) {
-            return true;
-        }
-
-        // emulate it by fetching and discarding rows, similarly to what PDO does in this case
-        // @link http://php.net/manual/en/pdostatement.closecursor.php
-        // @link https://github.com/php/php-src/blob/php-7.0.11/ext/pdo/pdo_stmt.c#L2075
-        // deliberately do not consider multiple result sets, since doctrine/dbal doesn't support them
-        while (sqlsrv_fetch($this->stmt)) {
-        }
-
-        $this->result = false;
+        $this->free();
 
         return true;
     }
@@ -498,6 +488,23 @@ class SQLSrvStatement implements IteratorAggregate, Statement, Result
         return sqlsrv_rows_affected($this->stmt) ?: 0;
     }
 
+    public function free(): void
+    {
+        // not having the result means there's nothing to close
+        if ($this->stmt === null || ! $this->result) {
+            return;
+        }
+
+        // emulate it by fetching and discarding rows, similarly to what PDO does in this case
+        // @link http://php.net/manual/en/pdostatement.closecursor.php
+        // @link https://github.com/php/php-src/blob/php-7.0.11/ext/pdo/pdo_stmt.c#L2075
+        // deliberately do not consider multiple result sets, since doctrine/dbal doesn't support them
+        while (sqlsrv_fetch($this->stmt)) {
+        }
+
+        $this->result = false;
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Portability/Statement.php

@@ -67,6 +67,8 @@ class Statement implements IteratorAggregate, DriverStatement, Result
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use free() instead.
      */
     public function closeCursor()
     {
@@ -270,6 +272,17 @@ class Statement implements IteratorAggregate, DriverStatement, Result
         return $this->fixResultSet($data, true, false);
     }
 
+    public function free(): void
+    {
+        if ($this->stmt instanceof Result) {
+            $this->stmt->free();
+
+            return;
+        }
+
+        $this->stmt->closeCursor();
+    }
+
     /**
      * @param mixed $result
      *

lib/Doctrine/DBAL/Statement.php

@@ -182,6 +182,8 @@ class Statement implements IteratorAggregate, DriverStatement, Result
     /**
      * Closes the cursor, freeing the database resources used by this statement.
      *
+     * @deprecated Use Result::free() instead.
+     *
      * @return bool TRUE on success, FALSE on failure.
      */
     public function closeCursor()
@@ -471,6 +473,17 @@ class Statement implements IteratorAggregate, DriverStatement, Result
         return $this->stmt->rowCount();
     }
 
+    public function free(): void
+    {
+        if ($this->stmt instanceof Result) {
+            $this->stmt->free();
+
+            return;
+        }
+
+        $this->stmt->closeCursor();
+    }
+
     /**
      * Gets the wrapped driver statement.
      *