Merge branch '3.7.x' into 4.0.x

* 3.7.x:
  Run tests against Postgres 16 (doctrine#6154)
  PHPStan 1.10.34, PHPUnit 9.6.12 (doctrine#6151)
  Bump CI workflows (doctrine#6152)
  Add a configuration setting to disable generating type comments (doctrine#6150)
  Fix invalid SQL in the document
  docs: link to the testing guidelines in CONTRIBUTING.md
  Fix IBM DB2 tests
  Implement binary array parameter type
  Document `driverOptions` for SQL Server connections (doctrine#6140)

.github/workflows/coding-standards.yml

@@ -25,4 +25,4 @@ on:
 jobs:
   coding-standards:
     name: "Coding Standards"
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@3.0.0"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@3.1.0"

.github/workflows/continuous-integration.yml

@@ -56,7 +56,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -122,7 +122,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -178,7 +178,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -216,15 +216,16 @@ jobs:
         postgres-version:
           - "10"
           - "15"
+          - "16"
         extension:
           - "pgsql"
           - "pdo_pgsql"
         include:
           - php-version: "8.2"
-            postgres-version: "15"
+            postgres-version: "16"
             extension: "pgsql"
           - php-version: "8.3"
-            postgres-version: "15"
+            postgres-version: "16"
             extension: "pdo_pgsql"
 
     services:
@@ -241,7 +242,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -310,7 +311,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -381,7 +382,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -451,7 +452,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -511,7 +512,7 @@ jobs:
         run: "docker exec ${{ job.services.ibm_db2.id }} su - db2inst1 -c 'db2 -t CONNECT TO doctrine; db2 -t CREATE USER TEMPORARY TABLESPACE doctrine_tbsp PAGESIZE 4 K;'"
 
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -557,7 +558,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
@@ -590,7 +591,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 

.github/workflows/release-on-milestone-closed.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Release"
         uses: "laminas/automatic-releases@1.24.0"

.github/workflows/static-analysis.yml

@@ -38,7 +38,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
@@ -64,7 +64,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2

CONTRIBUTING.md

@@ -1,4 +1,6 @@
+This repository has [guidelines specific to testing][testing guidelines], and
 Doctrine has [general contributing guidelines][contributor workflow], make
-sure you follow them.
+sure you follow both.
 
 [contributor workflow]: https://www.doctrine-project.org/contribute/index.html
+[testing guidelines]: https://www.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/testing.html

composer.json

@@ -41,7 +41,7 @@
         "doctrine/coding-standard": "12.0.0",
         "fig/log-test": "^1",
         "jetbrains/phpstorm-stubs": "2023.2",
-        "phpstan/phpstan": "1.10.32",
+        "phpstan/phpstan": "1.10.34",
         "phpstan/phpstan-phpunit": "1.3.14",
         "phpstan/phpstan-strict-rules": "^1.5",
         "phpunit/phpunit": "10.2.2",

docs/en/reference/configuration.rst

@@ -330,6 +330,7 @@ pdo_sqlsrv / sqlsrv
 -  ``host`` (string): Hostname of the database to connect to.
 -  ``port`` (integer): Port of the database to connect to.
 -  ``dbname`` (string): Name of the database/schema to connect to.
+-  ``driverOptions`` (array): Any supported options found on `https://learn.microsoft.com/en-us/sql/connect/php/connection-options`
 
 ibm_db2
 ^^^^^^^

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

@@ -253,10 +253,12 @@ 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 four special binding types that describe a list of integers, regular, ascii or binary strings:
 
 -   ``\Doctrine\DBAL\ArrayParameterType::INTEGER``
 -   ``\Doctrine\DBAL\ArrayParameterType::STRING``
+-   ``\Doctrine\DBAL\ArrayParameterType::ASCII``
+-   ``\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:
@@ -538,4 +540,4 @@ given data.
 
     <?php
     $conn->update('user', ['username' => 'jwage'], ['id' => 1]);
-    // UPDATE user (username) VALUES (?) WHERE id = ? (jwage, 1)
+    // UPDATE user SET username = ? WHERE id = ? (jwage, 1)

phpstan.neon.dist

@@ -100,6 +100,11 @@ parameters:
         # Ignore the possible false return value of db2_num_rows().
         - '~^Method Doctrine\\DBAL\\Driver\\IBMDB2\\Connection\:\:exec\(\) should return int but returns int<0, max>\|false\.$~'
         - '~^Method Doctrine\\DBAL\\Driver\\IBMDB2\\Result\:\:rowCount\(\) should return int but returns int<0, max>\|false\.$~'
+
+        # TODO
+        -
+            message: '~^Property Doctrine\\DBAL\\Platforms\\AbstractPlatform\:\:\$disableTypeComments is never read, only written\.$~'
+            path: src/Platforms/AbstractPlatform.php
 includes:
     - vendor/phpstan/phpstan-phpunit/extension.neon
     - vendor/phpstan/phpstan-phpunit/rules.neon

psalm.xml.dist

@@ -173,6 +173,9 @@
             <errorLevel type="suppress">
                 <!-- $array[key($array)] is safe. -->
                 <file name="src/Query/QueryBuilder.php"/>
+
+                <!-- $binaryValues[$i - 100] is safe. -->
+                <file name="tests/Functional/BinaryDataAccessTest.php"/>
             </errorLevel>
         </PossiblyInvalidArrayOffset>
         <PossiblyNullArgument>

src/ArrayParameterType.php

@@ -21,13 +21,19 @@ enum ArrayParameterType
      */
     case ASCII;
 
+    /**
+     * Represents an array of ascii strings to be expanded by Doctrine SQL parsing.
+     */
+    case BINARY;
+
     /** @internal */
     public static function toElementParameterType(self $type): ParameterType
     {
         return match ($type) {
             self::INTEGER => ParameterType::INTEGER,
             self::STRING => ParameterType::STRING,
             self::ASCII => ParameterType::ASCII,
+            self::BINARY => ParameterType::BINARY,
         };
     }
 }

src/Configuration.php

@@ -33,6 +33,14 @@ class Configuration
      */
     protected bool $autoCommit = true;
 
+    /**
+     * Whether type comments should be disabled to provide the same DB schema than
+     * will be obtained with DBAL 4.x. This is useful when relying only on the
+     * platform-aware schema comparison (which does not need those type comments)
+     * rather than the deprecated legacy tooling.
+     */
+    private bool $disableTypeComments = false;
+
     private ?SchemaManagerFactory $schemaManagerFactory = null;
 
     public function __construct()
@@ -132,4 +140,17 @@ public function setSchemaManagerFactory(SchemaManagerFactory $schemaManagerFacto
 
         return $this;
     }
+
+    public function getDisableTypeComments(): bool
+    {
+        return $this->disableTypeComments;
+    }
+
+    /** @return $this */
+    public function setDisableTypeComments(bool $disableTypeComments): self
+    {
+        $this->disableTypeComments = $disableTypeComments;
+
+        return $this;
+    }
 }

src/Connection.php

@@ -188,6 +188,7 @@ public function getDatabasePlatform(): AbstractPlatform
             }
 
             $this->platform = $this->driver->getDatabasePlatform($versionProvider);
+            $this->platform->setDisableTypeComments($this->_config->getDisableTypeComments());
         }
 
         return $this->platform;

src/Platforms/AbstractPlatform.php

@@ -79,6 +79,14 @@ abstract class AbstractPlatform
      */
     protected ?KeywordList $_keywords = null;
 
+    private bool $disableTypeComments = false;
+
+    /** @internal */
+    final public function setDisableTypeComments(bool $value): void
+    {
+        $this->disableTypeComments = $value;
+    }
+
     /**
      * Returns the SQL snippet that declares a boolean column.
      *

tests/Connection/ExpandArrayParametersTest.php

@@ -14,6 +14,8 @@
 use Doctrine\DBAL\Types\Type;
 use PHPUnit\Framework\TestCase;
 
+use function hex2bin;
+
 /** @psalm-import-type WrapperParameterTypeArray from Connection */
 class ExpandArrayParametersTest extends TestCase
 {
@@ -107,16 +109,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,
@@ -126,6 +136,8 @@ public static function dataExpandListParameters(): iterable
                     ParameterType::BOOLEAN,
                     ParameterType::ASCII,
                     ParameterType::ASCII,
+                    ParameterType::BINARY,
+                    ParameterType::BINARY,
                 ],
             ],
             'Named: Very simple with param int' => [
@@ -323,6 +335,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,
+                ],
+            ],
         ];
     }