Replace the concept of the statement fetch modes with an explicit API

Author: morozov

UPGRADE.md

@@ -1,5 +1,15 @@
 # Upgrade to 3.0
 
+## Removed `FetchMode` and the corresponding methods
+
+1. The `FetchMode` class and the `setFetchMode()` method of the `Connection` and `Statement` interfaces are removed.
+2. The `Statement::fetch()` method is replaced with `fetchNumeric()`, `fetchAssociative()` and `fetchOne()`.
+3. The `Statement::fetchAll()` method is replaced with `fetchAllNumeric()`, `fetchAllAssociative()` and `fechColumn()`.
+4. The `Statement::fetchColumn()` method is replaced with `fetchOne()`.
+5. The `Connection::fetchArray()` and `fetchAssoc()` methods are replaced with `fetchNumeric()` and `fetchAssociative()` respectively.
+6. The `StatementIterator` class is removed. The usage of a `Statement` object as `Traversable` is no longer possible. Use `iterateNumeric()`, `iterateAssociative()` and `iterateColumn()` instead.
+7. Fetching data in mixed mode (former `FetchMode::MIXED`) is no longer possible.
+
 ## BC BREAK: Dropped handling of one-based numeric arrays of parameters in `Statement::execute()`
 
 The statement implementations no longer detect whether `$params` is a zero- or one-based array. A zero-based numeric array is expected.

docs/en/reference/caching.rst

@@ -42,7 +42,7 @@ object is closed:
 
     <?php
     $stmt = $conn->executeCacheQuery($query, $params, $types, new QueryCacheProfile(0, "some key"));
-    $data = $stmt->fetchAll();
+    $data = $stmt->fetchAllAssociative();
     $stmt->closeCursor(); // at this point the result is cached
 
 .. warning::

docs/en/reference/data-retrieval-and-manipulation.rst

@@ -41,7 +41,7 @@ the query until there are no more rows:
 
     <?php
 
-    while ($row = $stmt->fetch()) {
+    while (($row = $stmt->fetchAssociative()) !== false) {
         echo $row['headline'];
     }
 
@@ -308,7 +308,7 @@ Prepare a given SQL statement and return the
     <?php
     $statement = $conn->prepare('SELECT * FROM user');
     $statement->execute();
-    $users = $statement->fetchAll();
+    $users = $statement->fetchAllAssociative();
 
     /*
     array(
@@ -346,7 +346,7 @@ parameters to the execute method, then returning the statement:
 
     <?php
     $statement = $conn->executeQuery('SELECT * FROM user WHERE username = ?', array('jwage'));
-    $user = $statement->fetch();
+    $user = $statement->fetchAssociative();
 
     /*
     array(
@@ -360,15 +360,15 @@ to perform necessary type conversions between actual input
 parameters and expected database values. See the
 :ref:`Types <mappingMatrix>` section for more information.
 
-fetchAll()
-~~~~~~~~~~
+fetchAllAssociative()
+~~~~~~~~~~~~~~~~~~~~~
 
 Execute the query and fetch all results into an array:
 
 .. code-block:: php
 
     <?php
-    $users = $conn->fetchAll('SELECT * FROM user');
+    $users = $conn->fetchAllAssociative('SELECT * FROM user');
 
     /*
     array(
@@ -379,15 +379,15 @@ Execute the query and fetch all results into an array:
     )
     */
 
-fetchArray()
-~~~~~~~~~~~~
+fetchNumeric()
+~~~~~~~~~~~~~~
 
 Numeric index retrieval of first result row of the given query:
 
 .. code-block:: php
 
     <?php
-    $user = $conn->fetchArray('SELECT * FROM user WHERE username = ?', array('jwage'));
+    $user = $conn->fetchNumeric('SELECT * FROM user WHERE username = ?', array('jwage'));
 
     /*
     array(
@@ -396,26 +396,26 @@ Numeric index retrieval of first result row of the given query:
     )
     */
 
-fetchColumn()
-~~~~~~~~~~~~~
+fetchOne()
+~~~~~~~~~~
 
-Retrieve only the given column of the first result row.
+Retrieve only the value of the first column of the first result row.
 
 .. code-block:: php
 
     <?php
-    $username = $conn->fetchColumn('SELECT username FROM user WHERE id = ?', array(1), 0);
+    $username = $conn->fetchOne('SELECT username FROM user WHERE id = ?', array(1), 0);
     echo $username; // jwage
 
-fetchAssoc()
-~~~~~~~~~~~~
+fetchAssociative()
+~~~~~~~~~~~~~~~~~~
 
-Retrieve assoc row of the first result row.
+Retrieve associative array of the first result row.
 
 .. code-block:: php
 
     <?php
-    $user = $conn->fetchAssoc('SELECT * FROM user WHERE username = ?', array('jwage'));
+    $user = $conn->fetchAssociative('SELECT * FROM user WHERE username = ?', array('jwage'));
     /*
     array(
       'username' => 'jwage',

src/Cache/ArrayStatement.php

@@ -2,19 +2,13 @@
 
 namespace Doctrine\DBAL\Cache;
 
-use ArrayIterator;
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\ResultStatement;
-use Doctrine\DBAL\FetchMode;
-use Doctrine\DBAL\ForwardCompatibility\Driver\ResultStatement as ForwardCompatibleResultStatement;
-use InvalidArgumentException;
-use IteratorAggregate;
-use function array_merge;
 use function array_values;
 use function count;
 use function reset;
 
-class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
+class ArrayStatement implements ResultStatement
 {
     /** @var mixed[] */
     private $data;
@@ -25,9 +19,6 @@ class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompa
     /** @var int */
     private $num = 0;
 
-    /** @var int */
-    private $defaultFetchMode = FetchMode::MIXED;
-
     /**
      * @param mixed[] $data
      */
@@ -59,97 +50,12 @@ public function columnCount()
         return $this->columnCount;
     }
 
-    /**
-     * {@inheritdoc}
-     *
-     * @deprecated Use one of the fetch- or iterate-related methods.
-     */
-    public function setFetchMode($fetchMode)
-    {
-        $this->defaultFetchMode = $fetchMode;
-
-        return true;
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @deprecated Use iterateNumeric(), iterateAssociative() or iterateColumn() instead.
-     */
-    public function getIterator()
-    {
-        $data = $this->fetchAll();
-
-        return new ArrayIterator($data);
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @deprecated Use fetchNumeric(), fetchAssociative() or fetchOne() instead.
-     */
-    public function fetch($fetchMode = null)
-    {
-        if (! isset($this->data[$this->num])) {
-            return false;
-        }
-
-        $row       = $this->data[$this->num++];
-        $fetchMode = $fetchMode ?? $this->defaultFetchMode;
-
-        if ($fetchMode === FetchMode::ASSOCIATIVE) {
-            return $row;
-        }
-
-        if ($fetchMode === FetchMode::NUMERIC) {
-            return array_values($row);
-        }
-
-        if ($fetchMode === FetchMode::MIXED) {
-            return array_merge($row, array_values($row));
-        }
-
-        if ($fetchMode === FetchMode::COLUMN) {
-            return reset($row);
-        }
-
-        throw new InvalidArgumentException('Invalid fetch-style given for fetching result.');
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @deprecated Use fetchAllNumeric(), fetchAllAssociative() or fetchColumn() instead.
-     */
-    public function fetchAll($fetchMode = null)
-    {
-        $rows = [];
-        while ($row = $this->fetch($fetchMode)) {
-            $rows[] = $row;
-        }
-
-        return $rows;
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @deprecated Use fetchOne() instead.
-     */
-    public function fetchColumn()
-    {
-        $row = $this->fetch(FetchMode::NUMERIC);
-
-        // TODO: verify that return false is the correct behavior
-        return $row[0] ?? false;
-    }
-
     /**
      * {@inheritdoc}
      */
     public function fetchNumeric()
     {
-        $row = $this->doFetch();
+        $row = $this->fetch();
 
         if ($row === false) {
             return false;
@@ -163,15 +69,15 @@ public function fetchNumeric()
      */
     public function fetchAssociative()
     {
-        return $this->doFetch();
+        return $this->fetch();
     }
 
     /**
      * {@inheritdoc}
      */
     public function fetchOne()
     {
-        $row = $this->doFetch();
+        $row = $this->fetch();
 
         if ($row === false) {
             return false;
@@ -196,10 +102,18 @@ public function fetchAllAssociative() : array
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchColumn() : array
+    {
+        return FetchUtils::fetchColumn($this);
+    }
+
     /**
      * @return mixed|false
      */
-    private function doFetch()
+    private function fetch()
     {
         if (! isset($this->data[$this->num])) {
             return false;