Introduce Statement::fetchFirstColumn()

UPGRADE.md

@@ -4,7 +4,7 @@
 
 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.
+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()`.
 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()`.

lib/Doctrine/DBAL/Cache/ArrayStatement.php

@@ -201,6 +201,14 @@ class ArrayStatement implements IteratorAggregate, ResultStatement, ForwardCompa
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -277,6 +277,14 @@ class ResultCacheStatement implements IteratorAggregate, ResultStatement, Forwar
         return $this->data;
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * Returns the number of rows affected by the last DELETE, INSERT, or UPDATE statement
      * executed by the corresponding object.

lib/Doctrine/DBAL/Connection.php

@@ -991,6 +991,32 @@ class Connection implements DriverConnection
         }
     }
 
+    /**
+     * Prepares and executes an SQL query and returns the result as an array of the first column values.
+     *
+     * @param string                                           $query  The SQL query.
+     * @param array<int, mixed>|array<string, mixed>           $params The query parameters.
+     * @param array<int, int|string>|array<string, int|string> $types  The query parameter types.
+     *
+     * @return array<int,mixed>
+     *
+     * @throws DBALException
+     */
+    public function fetchFirstColumn(string $query, array $params = [], array $types = []) : array
+    {
+        try {
+            $stmt = $this->executeQuery($query, $params, $types);
+
+            if ($stmt instanceof ForwardCompatibleResultStatement) {
+                return $stmt->fetchFirstColumn();
+            }
+
+            return $stmt->fetchAll(FetchMode::COLUMN);
+        } catch (Throwable $e) {
+            throw DBALException::driverExceptionDuringQuery($this->_driver, $e, $query);
+        }
+    }
+
     /**
      * Prepares and executes an SQL query and returns the result as an iterator over rows represented as numeric arrays.
      *

lib/Doctrine/DBAL/Driver/FetchUtils.php

@@ -58,4 +58,20 @@ final class FetchUtils
 
         return $rows;
     }
+
+    /**
+     * @return array<int,mixed>
+     *
+     * @throws DriverException
+     */
+    public static function fetchFirstColumn(ResultStatement $stmt) : array
+    {
+        $rows = [];
+
+        while (($row = $stmt->fetchOne()) !== false) {
+            $rows[] = $row;
+        }
+
+        return $rows;
+    }
 }

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

@@ -408,6 +408,14 @@ class DB2Statement implements IteratorAggregate, Statement, ForwardCompatibleRes
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * {@inheritdoc}
      */

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

@@ -467,6 +467,14 @@ class MysqliStatement implements IteratorAggregate, Statement, ForwardCompatible
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * {@inheritdoc}
      */

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

@@ -591,6 +591,14 @@ class OCI8Statement implements IteratorAggregate, Statement, ForwardCompatibleRe
         return $this->doFetchAll(OCI_ASSOC, OCI_FETCHSTATEMENT_BY_ROW);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return $this->doFetchAll(OCI_NUM, OCI_FETCHSTATEMENT_BY_COLUMN)[0];
+    }
+
     /**
      * @return mixed|false
      */

lib/Doctrine/DBAL/Driver/PDOStatement.php

@@ -240,6 +240,14 @@ class PDOStatement extends \PDOStatement implements Statement, ForwardCompatible
         return $this->fetchAll(PDO::FETCH_ASSOC);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return $this->fetchAll(PDO::FETCH_COLUMN);
+    }
+
     /**
      * Converts DBAL parameter type to PDO parameter type
      *

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

@@ -368,6 +368,16 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement, ForwardCompa
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * @return array<int,mixed>
+     *
+     * @throws DriverException
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * {@inheritdoc}
      */

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

@@ -476,6 +476,14 @@ class SQLSrvStatement implements IteratorAggregate, Statement, ForwardCompatible
         return FetchUtils::fetchAllAssociative($this);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        return FetchUtils::fetchFirstColumn($this);
+    }
+
     /**
      * {@inheritdoc}
      */

lib/Doctrine/DBAL/ForwardCompatibility/Driver/ResultStatement.php

@@ -56,4 +56,13 @@ interface ResultStatement extends BaseResultStatement
      * @throws DriverException
      */
     public function fetchAllAssociative() : array;
+
+    /**
+     * Returns an array containing the values of the first column of the result set.
+     *
+     * @return array<int,mixed>
+     *
+     * @throws DriverException
+     */
+    public function fetchFirstColumn() : array;
 }

lib/Doctrine/DBAL/Portability/Statement.php

@@ -255,6 +255,20 @@ class Statement implements IteratorAggregate, DriverStatement, ForwardCompatible
         return $this->fixResultSet($data, true, true);
     }
 
+    /**
+     * {@inheritdoc}
+     */
+    public function fetchFirstColumn() : array
+    {
+        if ($this->stmt instanceof ForwardCompatibleResultStatement) {
+            $data = $this->stmt->fetchFirstColumn();
+        } else {
+            $data = $this->stmt->fetchAll(FetchMode::COLUMN);
+        }
+
+        return $this->fixResultSet($data, true, false);
+    }
+
     /**
      * @param mixed $result
      *

lib/Doctrine/DBAL/Statement.php

@@ -370,6 +370,24 @@ class Statement implements IteratorAggregate, DriverStatement, ForwardCompatible
         }
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @throws DBALException
+     */
+    public function fetchFirstColumn() : array
+    {
+        try {
+            if ($this->stmt instanceof ForwardCompatibleResultStatement) {
+                return $this->stmt->fetchFirstColumn();
+            }
+
+            return $this->stmt->fetchAll(FetchMode::COLUMN);
+        } catch (DriverException $e) {
+            throw DBALException::driverException($this->conn->getDriver(), $e);
+        }
+    }
+
     /**
      * {@inheritDoc}
      *

tests/Doctrine/Tests/DBAL/Functional/Connection/FetchTest.php

@@ -76,6 +76,15 @@ class FetchTest extends DbalFunctionalTestCase
         ], $this->connection->fetchAllAssociative($this->query));
     }
 
+    public function testFetchFirstColumn() : void
+    {
+        self::assertEquals([
+            'foo',
+            'bar',
+            'baz',
+        ], $this->connection->fetchFirstColumn($this->query));
+    }
+
     public function testIterateNumeric() : void
     {
         self::assertEquals([