Deprecated the concept of the fetch mode

UPGRADE.md

@@ -1,5 +1,15 @@
 # Upgrade to 2.11
 
+## 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()` and `fetchAllAssociative()`. There is no currently replacement for `Statement::fetchAll(FETCH_MODE::COLUMN)`. In a future major version, `fetchColumn()` will be used as a replacement.
+4. The `Statement::fetchColumn()` method is deprecated in favor of `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()`.
+7. Fetching data in mixed mode (`FetchMode::MIXED`) is deprecated.
+
 ## Deprecated `Connection::project()`
 
 The `Connection::project()` method is deprecated. Implement data transformation outside of DBAL.

composer.json

@@ -43,6 +43,7 @@
         "nikic/php-parser": "^4.4",
         "phpstan/phpstan": "^0.12",
         "phpunit/phpunit": "^8.4.1",
+        "slevomat/coding-standard": "^6.3.6",
         "symfony/console": "^2.0.5|^3.0|^4.0|^5.0",
         "vimeo/psalm": "^3.11"
     },

lib/Doctrine/DBAL/Cache/ArrayStatement.php

@@ -3,8 +3,10 @@
 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 PDO;
@@ -13,7 +15,7 @@
 use function count;
 use function reset;
 
-class ArrayStatement implements IteratorAggregate, ResultStatement
+class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
 {
     /** @var mixed[] */
     private $data;
@@ -60,6 +62,8 @@ public function columnCount()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use one of the fetch- or iterate-related methods.
      */
     public function setFetchMode($fetchMode, $arg2 = null, $arg3 = null)
     {
@@ -74,6 +78,8 @@ public function setFetchMode($fetchMode, $arg2 = null, $arg3 = null)
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use iterateNumeric(), iterateAssociative() or iterateColumn() instead.
      */
     public function getIterator()
     {
@@ -84,6 +90,8 @@ public function getIterator()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchNumeric(), fetchAssociative() or fetchOne() instead.
      */
     public function fetch($fetchMode = null, $cursorOrientation = PDO::FETCH_ORI_NEXT, $cursorOffset = 0)
     {
@@ -115,6 +123,8 @@ public function fetch($fetchMode = null, $cursorOrientation = PDO::FETCH_ORI_NEX
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchAllNumeric(), fetchAllAssociative() or fetchColumn() instead.
      */
     public function fetchAll($fetchMode = null, $fetchArgument = null, $ctorArgs = null)
     {
@@ -128,6 +138,8 @@ public function fetchAll($fetchMode = null, $fetchArgument = null, $ctorArgs = n
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchOne() instead.
      */
     public function fetchColumn($columnIndex = 0)
     {
@@ -136,4 +148,68 @@ public function fetchColumn($columnIndex = 0)
         // TODO: verify that return false is the correct behavior
         return $row[$columnIndex] ?? false;
     }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchNumeric()
+    {
+        $row = $this->doFetch();
+
+        if ($row === false) {
+            return false;
+        }
+
+        return array_values($row);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAssociative()
+    {
+        return $this->doFetch();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchOne()
+    {
+        $row = $this->doFetch();
+
+        if ($row === false) {
+            return false;
+        }
+
+        return reset($row);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAllNumeric() : array
+    {
+        return FetchUtils::fetchAllNumeric($this);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAllAssociative() : array
+    {
+        return FetchUtils::fetchAllAssociative($this);
+    }
+
+    /**
+     * @return mixed|false
+     */
+    private function doFetch()
+    {
+        if (! isset($this->data[$this->num])) {
+            return false;
+        }
+
+        return $this->data[$this->num++];
+    }
 }

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -4,9 +4,12 @@
 
 use ArrayIterator;
 use Doctrine\Common\Cache\Cache;
+use Doctrine\DBAL\Driver\DriverException;
+use Doctrine\DBAL\Driver\FetchUtils;
 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;
@@ -28,7 +31,7 @@
  * 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.
  */
-class ResultCacheStatement implements IteratorAggregate, ResultStatement
+class ResultCacheStatement implements IteratorAggregate, ResultStatement, ForwardCompatibleResultStatement
 {
     /** @var Cache */
     private $resultCache;
@@ -105,6 +108,8 @@ public function columnCount()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use one of the fetch- or iterate-related methods.
      */
     public function setFetchMode($fetchMode, $arg2 = null, $arg3 = null)
     {
@@ -115,6 +120,8 @@ public function setFetchMode($fetchMode, $arg2 = null, $arg3 = null)
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use iterateNumeric(), iterateAssociative() or iterateColumn() instead.
      */
     public function getIterator()
     {
@@ -125,6 +132,8 @@ public function getIterator()
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchNumeric(), fetchAssociative() or fetchOne() instead.
      */
     public function fetch($fetchMode = null, $cursorOrientation = PDO::FETCH_ORI_NEXT, $cursorOffset = 0)
     {
@@ -165,6 +174,8 @@ public function fetch($fetchMode = null, $cursorOrientation = PDO::FETCH_ORI_NEX
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchAllNumeric(), fetchAllAssociative() or fetchColumn() instead.
      */
     public function fetchAll($fetchMode = null, $fetchArgument = null, $ctorArgs = null)
     {
@@ -184,6 +195,8 @@ public function fetchAll($fetchMode = null, $fetchArgument = null, $ctorArgs = n
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated Use fetchOne() instead.
      */
     public function fetchColumn($columnIndex = 0)
     {
@@ -193,6 +206,64 @@ public function fetchColumn($columnIndex = 0)
         return $row[$columnIndex] ?? false;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchNumeric()
+    {
+        $row = $this->doFetch();
+
+        if ($row === false) {
+            return false;
+        }
+
+        return array_values($row);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAssociative()
+    {
+        return $this->doFetch();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchOne()
+    {
+        return FetchUtils::fetchOne($this);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAllNumeric() : array
+    {
+        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+            $data = $this->statement->fetchAllAssociative();
+        } else {
+            $data = $this->statement->fetchAll(FetchMode::ASSOCIATIVE);
+        }
+
+        return $this->store($data);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchAllAssociative() : array
+    {
+        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+            $data = $this->statement->fetchAllAssociative();
+        } else {
+            $data = $this->statement->fetchAll(FetchMode::ASSOCIATIVE);
+        }
+
+        return $this->store($data);
+    }
+
     /**
      * Returns the number of rows affected by the last DELETE, INSERT, or UPDATE statement
      * executed by the corresponding object.
@@ -210,4 +281,49 @@ public function rowCount()
 
         return $this->statement->rowCount();
     }
+
+    /**
+     * @return array<string,mixed>|false
+     *
+     * @throws DriverException
+     */
+    private function doFetch()
+    {
+        if ($this->data === null) {
+            $this->data = [];
+        }
+
+        if ($this->statement instanceof ForwardCompatibleResultStatement) {
+            $row = $this->statement->fetchAssociative();
+        } else {
+            $row = $this->statement->fetch(FetchMode::ASSOCIATIVE);
+        }
+
+        if ($row !== false) {
+            $this->data[] = $row;
+
+            return $row;
+        }
+
+        $this->emptied = true;
+
+        return false;
+    }
+
+    /**
+     * @param  array<int,array<mixed>> $data
+     *
+     * @return array<int,array<mixed>>
+     */
+    private function store(array $data) : array
+    {
+        foreach ($data as $key => $value) {
+            $data[$key] = [$value];
+        }
+
+        $this->data    = $data;
+        $this->emptied = true;
+
+        return $this->data;
+    }
 }