Replace the concept of statement fetch modes with the explicit API

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;