Implement binary array parameter type

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

@@ -248,10 +248,11 @@ SQL injection possibilities if not handled carefully.
 Doctrine DBAL implements a very powerful parsing process that will make this kind of prepared
 statement possible natively in the binding type system.
 The parsing necessarily comes with a performance overhead, but only if you really use a list of parameters.
-There are two special binding types that describe a list of integers or strings:
+There are three special binding types that describe a list of integers, regular strings or binary strings:
 
 -   ``\Doctrine\DBAL\ArrayParameterType::INTEGER``
 -   ``\Doctrine\DBAL\ArrayParameterType::STRING``
+-   ``\Doctrine\DBAL\ArrayParameterType::BINARY``
 
 Using one of these constants as a type you can activate the SQLParser inside Doctrine that rewrites
 the SQL and flattens the specified values into the set of parameters. Consider our previous example:

src/ArrayParameterType.php

@@ -19,12 +19,17 @@ final class ArrayParameterType
      */
     public const ASCII = ParameterType::ASCII + Connection::ARRAY_PARAM_OFFSET;
 
+    /**
+     * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
+     */
+    public const BINARY = ParameterType::BINARY + Connection::ARRAY_PARAM_OFFSET;
+
     /**
      * @internal
      *
-     * @psalm-param self::INTEGER|self::STRING|self::ASCII $type
+     * @psalm-param self::INTEGER|self::STRING|self::ASCII|self::BINARY $type
      *
-     * @psalm-return ParameterType::INTEGER|ParameterType::STRING|ParameterType::ASCII
+     * @psalm-return ParameterType::INTEGER|ParameterType::STRING|ParameterType::ASCII|ParameterType::BINARY
      */
     public static function toElementParameterType(int $type): int
     {

src/Connection.php

@@ -1915,6 +1915,7 @@ private function needsArrayParameterConversion(array $params, array $types): boo
                 $type === ArrayParameterType::INTEGER
                 || $type === ArrayParameterType::STRING
                 || $type === ArrayParameterType::ASCII
+                || $type === ArrayParameterType::BINARY
             ) {
                 return true;
             }

src/ExpandArrayParameters.php

@@ -101,6 +101,7 @@ private function acceptParameter($key, $value): void
             $type !== ArrayParameterType::INTEGER
             && $type !== ArrayParameterType::STRING
             && $type !== ArrayParameterType::ASCII
+            && $type !== ArrayParameterType::BINARY
         ) {
             $this->appendTypedParameter([$value], $type);
 

tests/Connection/ExpandArrayParametersTest.php

@@ -11,6 +11,8 @@
 use Doctrine\DBAL\Types\Type;
 use PHPUnit\Framework\TestCase;
 
+use function hex2bin;
+
 class ExpandArrayParametersTest extends TestCase
 {
     /** @return mixed[][] */
@@ -94,16 +96,24 @@ public static function dataExpandListParameters(): iterable
                 [1 => ParameterType::STRING, 2 => ParameterType::STRING],
             ],
             'Positional: explicit keys for array params and array types' => [
-                'SELECT * FROM Foo WHERE foo IN (?) AND bar IN (?) AND baz = ? AND bax IN (?)',
-                [1 => ['bar1', 'bar2'], 2 => true, 0 => [1, 2, 3], ['bax1', 'bax2']],
+                'SELECT * FROM Foo WHERE foo IN (?) AND bar IN (?) AND baz = ? AND bax IN (?) AND bay IN (?)',
+                [
+                    1 => ['bar1', 'bar2'],
+                    2 => true,
+                    0 => [1, 2, 3],
+                    ['bax1', 'bax2'],
+                    4 => [hex2bin('DEADBEEF'), hex2bin('C0DEF00D')],
+                ],
                 [
+                    4 => ArrayParameterType::BINARY,
                     3 => ArrayParameterType::ASCII,
                     2 => ParameterType::BOOLEAN,
                     1 => ArrayParameterType::STRING,
                     0 => ArrayParameterType::INTEGER,
                 ],
-                'SELECT * FROM Foo WHERE foo IN (?, ?, ?) AND bar IN (?, ?) AND baz = ? AND bax IN (?, ?)',
-                [1, 2, 3, 'bar1', 'bar2', true, 'bax1', 'bax2'],
+                'SELECT * FROM Foo WHERE foo IN (?, ?, ?) AND bar IN (?, ?) AND baz = ? AND bax IN (?, ?) ' .
+                    'AND bay IN (?, ?)',
+                [1, 2, 3, 'bar1', 'bar2', true, 'bax1', 'bax2', hex2bin('DEADBEEF'), hex2bin('C0DEF00D')],
                 [
                     ParameterType::INTEGER,
                     ParameterType::INTEGER,
@@ -113,6 +123,8 @@ public static function dataExpandListParameters(): iterable
                     ParameterType::BOOLEAN,
                     ParameterType::ASCII,
                     ParameterType::ASCII,
+                    ParameterType::BINARY,
+                    ParameterType::BINARY,
                 ],
             ],
             'Named: Very simple with param int' => [
@@ -310,6 +322,22 @@ public static function dataExpandListParameters(): iterable
                 ['foo', 'bar', 'baz'],
                 [1 => ParameterType::STRING, ParameterType::STRING],
             ],
+            'Named: Binary array with explicit types' => [
+                'SELECT * FROM Foo WHERE foo IN (:foo) OR bar IN (:bar)',
+                [
+                    'foo' => [hex2bin('DEADBEEF'), hex2bin('C0DEF00D')],
+                    'bar' => [hex2bin('DEADBEEF'), hex2bin('C0DEF00D')],
+                ],
+                ['foo' => ArrayParameterType::BINARY, 'bar' => ArrayParameterType::BINARY],
+                'SELECT * FROM Foo WHERE foo IN (?, ?) OR bar IN (?, ?)',
+                [hex2bin('DEADBEEF'), hex2bin('C0DEF00D'), hex2bin('DEADBEEF'), hex2bin('C0DEF00D')],
+                [
+                    ParameterType::BINARY,
+                    ParameterType::BINARY,
+                    ParameterType::BINARY,
+                    ParameterType::BINARY,
+                ],
+            ],
         ];
     }
 

tests/Functional/BinaryDataAccessTest.php

@@ -0,0 +1,270 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Functional;
+
+use Doctrine\DBAL\ArrayParameterType;
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Schema\Table;
+use Doctrine\DBAL\Tests\FunctionalTestCase;
+use Doctrine\DBAL\Tests\TestUtil;
+use Doctrine\DBAL\Types\Types;
+
+use function array_change_key_case;
+use function hex2bin;
+use function pack;
+
+use const CASE_LOWER;
+
+class BinaryDataAccessTest extends FunctionalTestCase
+{
+    protected function setUp(): void
+    {
+        if (TestUtil::isDriverOneOf('pdo_oci')) {
+            self::markTestSkipped("PDO_OCI doesn't support binding binary values");
+        }
+
+        $table = new Table('fetch_table');
+        $table->addColumn('test_int', 'integer');
+        $table->addColumn('test_binary', 'binary', ['notnull' => false, 'length' => 4]);
+        $table->setPrimaryKey(['test_int']);
+
+        $this->dropAndCreateTable($table);
+
+        $this->connection->insert('fetch_table', [
+            'test_int' => 1,
+            'test_binary' => hex2bin('C0DEF00D'),
+        ], [
+            'test_binary' => ParameterType::BINARY,
+        ]);
+    }
+
+    public function testPrepareWithBindValue(): void
+    {
+        $sql  = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $stmt = $this->connection->prepare($sql);
+
+        $stmt->bindValue(1, 1);
+        $stmt->bindValue(2, hex2bin('C0DEF00D'), ParameterType::BINARY);
+
+        $row = $stmt->executeQuery()->fetchAssociative();
+
+        self::assertIsArray($row);
+        $row = array_change_key_case($row, CASE_LOWER);
+        self::assertEquals(['test_int' => 1, 'test_binary' => hex2bin('C0DEF00D')], $row);
+    }
+
+    public function testPrepareWithFetchAllAssociative(): void
+    {
+        $paramInt = 1;
+        $paramBin = hex2bin('C0DEF00D');
+
+        $sql  = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $stmt = $this->connection->prepare($sql);
+
+        $stmt->bindValue(1, $paramInt);
+        $stmt->bindValue(2, $paramBin, ParameterType::BINARY);
+
+        $rows    = $stmt->executeQuery()->fetchAllAssociative();
+        $rows[0] = array_change_key_case($rows[0], CASE_LOWER);
+        self::assertEquals(['test_int' => $paramInt, 'test_binary' => $paramBin], $rows[0]);
+    }
+
+    public function testPrepareWithFetchOne(): void
+    {
+        $paramInt = 1;
+        $paramBin = hex2bin('C0DEF00D');
+
+        $sql  = 'SELECT test_int FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $stmt = $this->connection->prepare($sql);
+
+        $stmt->bindValue(1, $paramInt);
+        $stmt->bindValue(2, $paramBin, ParameterType::BINARY);
+
+        $column = $stmt->executeQuery()->fetchOne();
+        self::assertEquals(1, $column);
+    }
+
+    public function testFetchAllAssociative(): void
+    {
+        $sql  = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $data = $this->connection->fetchAllAssociative($sql, [1, hex2bin('C0DEF00D')], [1 => ParameterType::BINARY]);
+
+        self::assertCount(1, $data);
+
+        $row = $data[0];
+        self::assertCount(2, $row);
+
+        $row = array_change_key_case($row, CASE_LOWER);
+        self::assertEquals(1, $row['test_int']);
+        self::assertEquals(hex2bin('C0DEF00D'), $row['test_binary']);
+    }
+
+    public function testFetchAllWithTypes(): void
+    {
+        $sql  = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $data = $this->connection->fetchAllAssociative(
+            $sql,
+            [1, hex2bin('C0DEF00D')],
+            [ParameterType::STRING, Types::BINARY],
+        );
+
+        self::assertCount(1, $data);
+
+        $row = $data[0];
+        self::assertCount(2, $row);
+
+        $row = array_change_key_case($row, CASE_LOWER);
+        self::assertEquals(1, $row['test_int']);
+        self::assertStringStartsWith(hex2bin('C0DEF00D'), $row['test_binary']);
+    }
+
+    public function testFetchAssociative(): void
+    {
+        $sql = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $row = $this->connection->fetchAssociative($sql, [1, hex2bin('C0DEF00D')], [1 => ParameterType::BINARY]);
+
+        self::assertNotFalse($row);
+
+        $row = array_change_key_case($row, CASE_LOWER);
+
+        self::assertEquals(1, $row['test_int']);
+        self::assertEquals(hex2bin('C0DEF00D'), $row['test_binary']);
+    }
+
+    public function testFetchAssocWithTypes(): void
+    {
+        $sql = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $row = $this->connection->fetchAssociative(
+            $sql,
+            [1, hex2bin('C0DEF00D')],
+            [ParameterType::STRING, Types::BINARY],
+        );
+
+        self::assertNotFalse($row);
+
+        $row = array_change_key_case($row, CASE_LOWER);
+
+        self::assertEquals(1, $row['test_int']);
+        self::assertStringStartsWith(hex2bin('C0DEF00D'), $row['test_binary']);
+    }
+
+    public function testFetchArray(): void
+    {
+        $sql = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $row = $this->connection->fetchNumeric($sql, [1, hex2bin('C0DEF00D')], [1 => ParameterType::BINARY]);
+        self::assertNotFalse($row);
+
+        self::assertEquals(1, $row[0]);
+        self::assertEquals(hex2bin('C0DEF00D'), $row[1]);
+    }
+
+    public function testFetchArrayWithTypes(): void
+    {
+        $sql = 'SELECT test_int, test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $row = $this->connection->fetchNumeric(
+            $sql,
+            [1, hex2bin('C0DEF00D')],
+            [ParameterType::STRING, Types::BINARY],
+        );
+
+        self::assertNotFalse($row);
+
+        $row = array_change_key_case($row, CASE_LOWER);
+
+        self::assertEquals(1, $row[0]);
+        self::assertStringStartsWith(hex2bin('C0DEF00D'), $row[1]);
+    }
+
+    public function testFetchColumn(): void
+    {
+        $sql     = 'SELECT test_int FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $testInt = $this->connection->fetchOne($sql, [1, hex2bin('C0DEF00D')], [1 => ParameterType::BINARY]);
+
+        self::assertEquals(1, $testInt);
+
+        $sql        = 'SELECT test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $testBinary = $this->connection->fetchOne($sql, [1, hex2bin('C0DEF00D')], [1 => ParameterType::BINARY]);
+
+        self::assertEquals(hex2bin('C0DEF00D'), $testBinary);
+    }
+
+    public function testFetchOneWithTypes(): void
+    {
+        $sql    = 'SELECT test_binary FROM fetch_table WHERE test_int = ? AND test_binary = ?';
+        $column = $this->connection->fetchOne(
+            $sql,
+            [1, hex2bin('C0DEF00D')],
+            [ParameterType::STRING, Types::BINARY],
+        );
+
+        self::assertIsString($column);
+
+        self::assertStringStartsWith(hex2bin('C0DEF00D'), $column);
+    }
+
+    public function testNativeArrayListSupport(): void
+    {
+        for ($i = 100; $i < 110; $i++) {
+            $this->connection->insert('fetch_table', [
+                'test_int' => $i,
+                'test_binary' => pack('L', $i),
+            ], [
+                'test_binary' => ParameterType::BINARY,
+            ]);
+        }
+
+        $result = $this->connection->executeQuery(
+            'SELECT test_int FROM fetch_table WHERE test_int IN (?)',
+            [[100, 101, 102, 103, 104]],
+            [ArrayParameterType::INTEGER],
+        );
+
+        $data = $result->fetchAllNumeric();
+        self::assertCount(5, $data);
+        self::assertEquals([[100], [101], [102], [103], [104]], $data);
+
+        $result = $this->connection->executeQuery(
+            'SELECT test_int FROM fetch_table WHERE test_binary IN (?)',
+            [
+                [
+                    pack('L', 100),
+                    pack('L', 101),
+                    pack('L', 102),
+                    pack('L', 103),
+                    pack('L', 104),
+                ],
+            ],
+            [ArrayParameterType::BINARY],
+        );
+
+        $data = $result->fetchAllNumeric();
+        self::assertCount(5, $data);
+        self::assertEquals([[100], [101], [102], [103], [104]], $data);
+
+        $result = $this->connection->executeQuery(
+            'SELECT test_binary FROM fetch_table WHERE test_binary IN (?)',
+            [
+                [
+                    pack('L', 100),
+                    pack('L', 101),
+                    pack('L', 102),
+                    pack('L', 103),
+                    pack('L', 104),
+                ],
+            ],
+            [ArrayParameterType::BINARY],
+        );
+
+        $data = $result->fetchFirstColumn();
+        self::assertCount(5, $data);
+        self::assertEquals([
+            pack('L', 100),
+            pack('L', 101),
+            pack('L', 102),
+            pack('L', 103),
+            pack('L', 104),
+        ], $data);
+    }
+}