Add the Result::getColumnName method

This method allows introspecting the shape of results by knowing the
name of columns.

UPGRADE.md

@@ -13,6 +13,11 @@ awareness about deprecated code.
 * Upgrade to MariaDB 10.5 or later.
 * Upgrade to MySQL 8.0 or later.
 
+## Add `Result::getColumnName()`
+
+Driver and middleware results need to implement a new method `getColumnName()` that gives access to the
+column name. Not doing so is deprecated.
+
 # Upgrade to 4.0
 
 ## BC BREAK: removed `AbstractMySQLPlatform` methods.

phpstan.neon.dist

@@ -103,6 +103,10 @@ parameters:
 
         # Required for Psalm compatibility
         - '~^Property Doctrine\\DBAL\\Tests\\Types\\BaseDateTypeTestCase\:\:\$currentTimezone \(non-empty-string\) does not accept string\.$~'
+
+        # Type check for legacy implementations of the Result interface
+        # TODO: remove in 5.0.0
+        - '~^Call to function method_exists\(\) with Doctrine\\DBAL\\Driver\\Result and ''getColumnName'' will always evaluate to true\.$~'
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon
     - vendor/phpstan/phpstan-phpunit/rules.neon

psalm.xml.dist

@@ -282,6 +282,8 @@
         </TypeDoesNotContainNull>
         <TypeDoesNotContainType>
             <errorLevel type="suppress">
+                <!-- See https://github.com/vimeo/psalm/issues/11008 -->
+                <file name="src/Driver/SQLite3/Result.php"/>
                 <!-- Ignore isset() checks in destructors. -->
                 <file name="src/Driver/PgSQL/Connection.php"/>
                 <file name="src/Driver/PgSQL/Statement.php"/>

src/Cache/ArrayResult.php

@@ -6,7 +6,9 @@
 
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\Result;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 
+use function array_keys;
 use function array_values;
 use function count;
 use function reset;
@@ -84,6 +86,15 @@ public function columnCount(): int
         return $this->columnCount;
     }
 
+    public function getColumnName(int $index): string
+    {
+        if ($this->data === [] || $index > count($this->data[0])) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        return array_keys($this->data[0])[$index];
+    }
+
     public function free(): void
     {
         $this->data = [];

src/Driver/IBMDB2/Result.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\IBMDB2\Exception\StatementError;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 
 use function db2_fetch_array;
 use function db2_fetch_assoc;
@@ -99,6 +100,17 @@ public function columnCount(): int
         return 0;
     }
 
+    public function getColumnName(int $index): string
+    {
+        $name = db2_field_name($this->statement, $index);
+
+        if ($name === false) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        return $name;
+    }
+
     public function free(): void
     {
         db2_free_result($this->statement);

src/Driver/Middleware/AbstractResultMiddleware.php

@@ -5,6 +5,11 @@
 namespace Doctrine\DBAL\Driver\Middleware;
 
 use Doctrine\DBAL\Driver\Result;
+use LogicException;
+
+use function get_debug_type;
+use function method_exists;
+use function sprintf;
 
 abstract class AbstractResultMiddleware implements Result
 {
@@ -61,6 +66,18 @@ public function columnCount(): int
         return $this->wrappedResult->columnCount();
     }
 
+    public function getColumnName(int $index): string
+    {
+        if (! method_exists($this->wrappedResult, 'getColumnName')) {
+            throw new LogicException(sprintf(
+                'The driver result %s does not support accessing the column name.',
+                get_debug_type($this->wrappedResult),
+            ));
+        }
+
+        return $this->wrappedResult->getColumnName($index);
+    }
+
     public function free(): void
     {
         $this->wrappedResult->free();

src/Driver/Mysqli/Result.php

@@ -8,6 +8,7 @@
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\Mysqli\Exception\StatementError;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 use mysqli_sql_exception;
 use mysqli_stmt;
 
@@ -157,6 +158,11 @@ public function columnCount(): int
         return $this->statement->field_count;
     }
 
+    public function getColumnName(int $index): string
+    {
+        return $this->columnNames[$index] ?? throw InvalidColumnIndex::new($index);
+    }
+
     public function free(): void
     {
         $this->statement->free_result();

src/Driver/OCI8/Result.php

@@ -8,6 +8,7 @@
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\OCI8\Exception\Error;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 
 use function oci_cancel;
 use function oci_error;
@@ -95,6 +96,18 @@ public function columnCount(): int
         return 0;
     }
 
+    public function getColumnName(int $index): string
+    {
+        // OCI expects a 1-based index while DBAL works with a O-based index.
+        $name = oci_field_name($this->statement, $index + 1);
+
+        if ($name === false) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        return $name;
+    }
+
     public function free(): void
     {
         oci_cancel($this->statement);

src/Driver/PDO/Result.php

@@ -5,6 +5,7 @@
 namespace Doctrine\DBAL\Driver\PDO;
 
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 use PDO;
 use PDOException;
 use PDOStatement;
@@ -73,6 +74,21 @@ public function columnCount(): int
         }
     }
 
+    public function getColumnName(int $index): string
+    {
+        try {
+            $meta = $this->statement->getColumnMeta($index);
+
+            if ($meta === false) {
+                throw InvalidColumnIndex::new($index);
+            }
+
+            return $meta['name'];
+        } catch (PDOException $exception) {
+            throw Exception::new($exception);
+        }
+    }
+
     public function free(): void
     {
         $this->statement->closeCursor();

src/Driver/PgSQL/Result.php

@@ -7,7 +7,9 @@
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\PgSQL\Exception\UnexpectedValue;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 use PgSql\Result as PgSqlResult;
+use ValueError;
 
 use function array_keys;
 use function array_map;
@@ -145,6 +147,19 @@ public function columnCount(): int
         return pg_num_fields($this->result);
     }
 
+    public function getColumnName(int $index): string
+    {
+        if ($this->result === null) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        try {
+            return pg_field_name($this->result, $index);
+        } catch (ValueError) {
+            throw InvalidColumnIndex::new($index);
+        }
+    }
+
     public function free(): void
     {
         if ($this->result === null) {

src/Driver/Result.php

@@ -6,6 +6,8 @@
 
 /**
  * Driver-level statement execution result.
+ *
+ * @method string getColumnName(int $index)
  */
 interface Result
 {

src/Driver/SQLSrv/Result.php

@@ -6,9 +6,11 @@
 
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 
 use function sqlsrv_fetch;
 use function sqlsrv_fetch_array;
+use function sqlsrv_field_metadata;
 use function sqlsrv_num_fields;
 use function sqlsrv_rows_affected;
 
@@ -87,6 +89,17 @@ public function columnCount(): int
         return 0;
     }
 
+    public function getColumnName(int $index): string
+    {
+        $meta = sqlsrv_field_metadata($this->statement);
+
+        if ($meta === false || ! isset($meta[$index])) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        return $meta[$index]['Name'];
+    }
+
     public function free(): void
     {
         // emulate it by fetching and discarding rows, similarly to what PDO does in this case

src/Driver/SQLite3/Result.php

@@ -6,6 +6,7 @@
 
 use Doctrine\DBAL\Driver\FetchUtils;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
+use Doctrine\DBAL\Exception\InvalidColumnIndex;
 use SQLite3Result;
 
 use const SQLITE3_ASSOC;
@@ -76,6 +77,21 @@ public function columnCount(): int
         return $this->result->numColumns();
     }
 
+    public function getColumnName(int $index): string
+    {
+        if ($this->result === null) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        $name = $this->result->columnName($index);
+
+        if ($name === false) {
+            throw InvalidColumnIndex::new($index);
+        }
+
+        return $name;
+    }
+
     public function free(): void
     {
         if ($this->result === null) {

src/Exception/InvalidColumnIndex.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Exception;
+
+use Doctrine\DBAL\Exception;
+use LogicException;
+
+use function sprintf;
+
+/** @psalm-immutable */
+final class InvalidColumnIndex extends LogicException implements Exception
+{
+    public static function new(int $index): self
+    {
+        return new self(sprintf('Invalid column index "%s".', $index));
+    }
+}

src/Portability/Converter.php

@@ -11,6 +11,8 @@
 use function array_reduce;
 use function is_string;
 use function rtrim;
+use function strtolower;
+use function strtoupper;
 
 use const CASE_LOWER;
 use const CASE_UPPER;
@@ -26,6 +28,7 @@ final class Converter
     private readonly Closure $convertAllNumeric;
     private readonly Closure $convertAllAssociative;
     private readonly Closure $convertFirstColumn;
+    private readonly Closure $convertColumnName;
 
     /**
      * @param bool                                   $convertEmptyStringToNull Whether each empty string should
@@ -48,6 +51,12 @@ public function __construct(bool $convertEmptyStringToNull, bool $rightTrimStrin
         $this->convertAllNumeric     = $this->createConvertAll($convertNumeric);
         $this->convertAllAssociative = $this->createConvertAll($convertAssociative);
         $this->convertFirstColumn    = $this->createConvertAll($convertValue);
+
+        $this->convertColumnName = match ($case) {
+            null => static fn (string $name) => $name,
+            self::CASE_LOWER => strtolower(...),
+            self::CASE_UPPER => strtoupper(...),
+        };
     }
 
     /**
@@ -105,6 +114,11 @@ public function convertFirstColumn(array $data): array
         return ($this->convertFirstColumn)($data);
     }
 
+    public function convertColumnName(string $name): string
+    {
+        return ($this->convertColumnName)($name);
+    }
+
     /**
      * @param T $value
      *

src/Portability/Result.php

@@ -65,4 +65,11 @@ public function fetchFirstColumn(): array
             parent::fetchFirstColumn(),
         );
     }
+
+    public function getColumnName(int $index): string
+    {
+        return $this->converter->convertColumnName(
+            parent::getColumnName($index)
+        );
+    }
 }