Merge pull request #4338 from morozov/issues/4289

Add Statement::fetchAllKeyValue() and ::iterateKeyValue()

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

@@ -379,6 +379,25 @@ Execute the query and fetch all results into an array:
     )
     */
 
+fetchAllKeyValue()
+~~~~~~~~~~~~~~~~~~
+
+Execute the query and fetch the first two columns into an associative array as keys and values respectively:
+
+.. code-block:: php
+
+    <?php
+    $users = $conn->fetchAllKeyValue('SELECT username, password FROM user');
+
+    /*
+    array(
+      'jwage' => 'changeme',
+    )
+    */
+
+.. note::
+   All additional columns will be ignored and are only allowed to be selected by DBAL for its internal purposes.
+
 fetchNumeric()
 ~~~~~~~~~~~~~~
 
@@ -425,6 +444,21 @@ Retrieve associative array of the first result row.
 
 There are also convenience methods for data manipulation queries:
 
+iterateKeyValue()
+~~~~~~~~~~~~~~~~~
+
+Execute the query and iterate over the first two columns as keys and values respectively:
+
+.. code-block:: php
+
+    <?php
+    foreach ($conn->iterateKeyValue('SELECT username, password FROM user') as $username => $password) {
+        // ...
+    }
+
+.. note::
+   All additional columns will be ignored and are only allowed to be selected by DBAL for its internal purposes.
+
 delete()
 ~~~~~~~~~
 

lib/Doctrine/DBAL/Connection.php

@@ -15,6 +15,7 @@
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
 use Doctrine\DBAL\Exception\ConnectionLost;
 use Doctrine\DBAL\Exception\InvalidArgumentException;
+use Doctrine\DBAL\Exception\NoKeyValue;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Query\Expression\ExpressionBuilder;
 use Doctrine\DBAL\Query\QueryBuilder;
@@ -985,6 +986,33 @@ public function fetchAllAssociative(string $query, array $params = [], array $ty
         }
     }
 
+    /**
+     * Prepares and executes an SQL query and returns the result as an associative array with the keys
+     * mapped to the first column and the values mapped to the second column.
+     *
+     * @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<mixed,mixed>
+     *
+     * @throws Exception
+     */
+    public function fetchAllKeyValue(string $query, array $params = [], array $types = []): array
+    {
+        $stmt = $this->executeQuery($query, $params, $types);
+
+        $this->ensureHasKeyValue($stmt);
+
+        $data = [];
+
+        foreach ($stmt->fetchAll(FetchMode::NUMERIC) as [$key, $value]) {
+            $data[$key] = $value;
+        }
+
+        return $data;
+    }
+
     /**
      * Prepares and executes an SQL query and returns the result as an array of the first column values.
      *
@@ -1068,6 +1096,29 @@ public function iterateAssociative(string $query, array $params = [], array $typ
         }
     }
 
+    /**
+     * Prepares and executes an SQL query and returns the result as an iterator with the keys
+     * mapped to the first column and the values mapped to the second column.
+     *
+     * @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 Traversable<mixed,mixed>
+     *
+     * @throws Exception
+     */
+    public function iterateKeyValue(string $query, array $params = [], array $types = []): Traversable
+    {
+        $stmt = $this->executeQuery($query, $params, $types);
+
+        $this->ensureHasKeyValue($stmt);
+
+        while (($row = $stmt->fetch(FetchMode::NUMERIC)) !== false) {
+            yield $row[0] => $row[1];
+        }
+    }
+
     /**
      * Prepares and executes an SQL query and returns the result as an iterator over the first column values.
      *
@@ -2055,4 +2106,13 @@ private function throw(Exception $e): void
 
         throw $e;
     }
+
+    private function ensureHasKeyValue(ResultStatement $stmt): void
+    {
+        $columnCount = $stmt->columnCount();
+
+        if ($columnCount < 2) {
+            throw NoKeyValue::fromColumnCount($columnCount);
+        }
+    }
 }

lib/Doctrine/DBAL/Exception/NoKeyValue.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Doctrine\DBAL\Exception;
+
+use Doctrine\DBAL\Exception;
+
+use function sprintf;
+
+/**
+ * @internal
+ *
+ * @psalm-immutable
+ */
+final class NoKeyValue extends Exception
+{
+    public static function fromColumnCount(int $columnCount): self
+    {
+        return new self(
+            sprintf(
+                'Fetching as key-value pairs requires the result to contain at least 2 columns, %d given.',
+                $columnCount
+            )
+        );
+    }
+}

lib/Doctrine/DBAL/Statement.php

@@ -5,6 +5,7 @@
 use Doctrine\DBAL\Abstraction\Result;
 use Doctrine\DBAL\Driver\Exception;
 use Doctrine\DBAL\Driver\Statement as DriverStatement;
+use Doctrine\DBAL\Exception\NoKeyValue;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Types\Type;
 use IteratorAggregate;
@@ -375,6 +376,28 @@ public function fetchAllAssociative(): array
         }
     }
 
+    /**
+     * Returns an associative array with the keys mapped to the first column and the values mapped to the second column.
+     *
+     * The result must contain at least two columns.
+     *
+     * @return array<mixed,mixed>
+     *
+     * @throws Exception
+     */
+    public function fetchAllKeyValue(): array
+    {
+        $this->ensureHasKeyValue();
+
+        $data = [];
+
+        foreach ($this->fetchAllNumeric() as [$key, $value]) {
+            $data[$key] = $value;
+        }
+
+        return $data;
+    }
+
     /**
      * {@inheritdoc}
      *
@@ -441,6 +464,25 @@ public function iterateAssociative(): Traversable
         }
     }
 
+    /**
+     * Returns an iterator over the result set with the keys mapped to the first column
+     * and the values mapped to the second column.
+     *
+     * The result must contain at least two columns.
+     *
+     * @return Traversable<mixed,mixed>
+     *
+     * @throws Exception
+     */
+    public function iterateKeyValue(): Traversable
+    {
+        $this->ensureHasKeyValue();
+
+        foreach ($this->iterateNumeric() as [$key, $value]) {
+            yield $key => $value;
+        }
+    }
+
     /**
      * {@inheritDoc}
      *
@@ -495,4 +537,13 @@ public function getWrappedStatement()
     {
         return $this->stmt;
     }
+
+    private function ensureHasKeyValue(): void
+    {
+        $columnCount = $this->columnCount();
+
+        if ($columnCount < 2) {
+            throw NoKeyValue::fromColumnCount($columnCount);
+        }
+    }
 }

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

@@ -2,6 +2,8 @@
 
 namespace Doctrine\Tests\DBAL\Functional\Connection;
 
+use Doctrine\DBAL\Exception\NoKeyValue;
+use Doctrine\DBAL\Platforms\SQLServer2012Platform;
 use Doctrine\Tests\DbalFunctionalTestCase;
 use Doctrine\Tests\TestUtil;
 
@@ -77,6 +79,53 @@ public function testFetchAllAssociative(): void
         ], $this->connection->fetchAllAssociative($this->query));
     }
 
+    public function testFetchAllKeyValue(): void
+    {
+        self::assertEquals([
+            'foo' => 1,
+            'bar' => 2,
+            'baz' => 3,
+        ], $this->connection->fetchAllKeyValue($this->query));
+    }
+
+    public function testStatementFetchAllKeyValue(): void
+    {
+        $stmt = $this->connection->prepare($this->query);
+        $stmt->execute();
+
+        self::assertEquals([
+            'foo' => 1,
+            'bar' => 2,
+            'baz' => 3,
+        ], $stmt->fetchAllKeyValue());
+    }
+
+    /**
+     * This test covers the requirement for the statement result to have at least two columns,
+     * not exactly two as PDO requires.
+     */
+    public function testFetchAllKeyValueWithLimit(): void
+    {
+        $platform = $this->connection->getDatabasePlatform();
+
+        if ($platform instanceof SQLServer2012Platform) {
+            self::markTestSkipped('See https://github.com/doctrine/dbal/issues/2374');
+        }
+
+        $query = $platform->modifyLimitQuery($this->query, 1, 1);
+
+        self::assertEquals(['bar' => 2], $this->connection->fetchAllKeyValue($query));
+    }
+
+    public function testFetchAllKeyValueOneColumn(): void
+    {
+        $sql = $this->connection->getDatabasePlatform()
+            ->getDummySelectSQL();
+
+        $this->expectException(NoKeyValue::class);
+        $this->connection->fetchAllKeyValue($sql);
+    }
+
     public function testFetchFirstColumn(): void
     {
         self::assertEquals([
@@ -113,6 +162,36 @@ public function testIterateAssociative(): void
         ], iterator_to_array($this->connection->iterateAssociative($this->query)));
     }
 
+    public function testIterateKeyValue(): void
+    {
+        self::assertEquals([
+            'foo' => 1,
+            'bar' => 2,
+            'baz' => 3,
+        ], iterator_to_array($this->connection->iterateKeyValue($this->query)));
+    }
+
+    public function testStatementKeyValue(): void
+    {
+        $stmt = $this->connection->prepare($this->query);
+        $stmt->execute();
+
+        self::assertEquals([
+            'foo' => 1,
+            'bar' => 2,
+            'baz' => 3,
+        ], iterator_to_array($stmt->iterateKeyValue()));
+    }
+
+    public function testIterateKeyValueOneColumn(): void
+    {
+        $sql = $this->connection->getDatabasePlatform()
+            ->getDummySelectSQL();
+
+        $this->expectException(NoKeyValue::class);
+        iterator_to_array($this->connection->iterateKeyValue($sql));
+    }
+
     public function testIterateColumn(): void
     {
         self::assertEquals([