Merge branch '4.4.x' into 5.0.x

* 4.4.x:
  CI: Update SQL Server to version 2022 (doctrine#7069)
  fix(MariaDb): add support of new reserved word `VECTOR` (11.7+) (doctrine#7061)
  Improve deprecation
  Update schema definition documentaion
  Fix binding null as a boolean parameter on pgsql (doctrine#7059)
  Use provided length for enum type if given for non-mysql platform (doctrine#7034)

Author: derrabus

.github/workflows/phpunit-sqlserver.yml

@@ -19,7 +19,7 @@ jobs:
 
     services:
       sqlserver:
-        image: mcr.microsoft.com/mssql/server:2019-latest
+        image: mcr.microsoft.com/mssql/server:2022-latest
         ports:
           - '1433:1433'
         env:

docs/en/reference/schema-representation.rst

@@ -12,32 +12,86 @@ Metadata model. Up to very specific functionality of your database
 system this allows you to generate SQL code that makes your Domain
 model work.
 
-You will be pleased to hear, that Schema representation is
-completely decoupled from the Doctrine ORM though, that is you can
-also use it in any other project to implement database migrations
+Schema representation is completely decoupled from the Doctrine ORM.
+You can also use it in any other project to implement database migrations
 or for SQL schema generation for any metadata model that your
-application has. You can easily generate a Schema, as a simple
-example shows:
+application has. You can generate a Schema, as the example below
+shows:
 
 .. code-block:: php
 
     <?php
-    $schema = new \Doctrine\DBAL\Schema\Schema();
-    $myTable = $schema->createTable("my_table");
-    $myTable->addColumn("id", "integer", ["unsigned" => true]);
-    $myTable->addColumn("username", "string", ["length" => 32]);
-    $myTable->setPrimaryKey(["id"]);
-    $myTable->addUniqueIndex(["username"]);
-    $myTable->setComment('Some comment');
-    $schema->createSequence("my_table_seq");
-
-    $myForeign = $schema->createTable("my_foreign");
-    $myForeign->addColumn("id", "integer");
-    $myForeign->addColumn("user_id", "integer");
-    $myForeign->addForeignKeyConstraint($myTable, ["user_id"], ["id"], ["onUpdate" => "CASCADE"]);
-
-    $queries = $schema->toSql($myPlatform); // get queries to create this schema.
-    $dropSchema = $schema->toDropSql($myPlatform); // get queries to safely delete this schema.
+
+    use Doctrine\DBAL\Schema\Column;
+    use Doctrine\DBAL\Schema\ForeignKeyConstraint;
+    use Doctrine\DBAL\Schema\ForeignKeyConstraint\ReferentialAction;
+    use Doctrine\DBAL\Schema\Index;
+    use Doctrine\DBAL\Schema\Index\IndexType;
+    use Doctrine\DBAL\Schema\PrimaryKeyConstraint;
+    use Doctrine\DBAL\Schema\Schema;
+    use Doctrine\DBAL\Schema\Table;
+
+    $user = Table::editor()
+        ->setUnquotedName('user')
+        ->addColumn(
+            Column::editor()
+                ->setUnquotedName('id')
+                ->setTypeName('integer')
+                ->setUnsigned(true)
+                ->create()
+        )
+        ->addColumn(
+            Column::editor()
+                ->setUnquotedName('username')
+                ->setTypeName('string')
+                ->setLength(32)
+                ->create()
+        )
+        ->addPrimaryKeyConstraint(
+            PrimaryKeyConstraint::editor()
+                ->setUnquotedColumnNames('id')
+                ->create()
+        )
+        ->addIndex(
+            Index::editor()
+                ->setUnquotedName('idx_username')
+                ->setUnquotedColumnNames('username')
+                ->setType(IndexType::UNIQUE)
+                ->create()
+        )
+        ->setComment('User table')
+        ->create();
+
+    $post = Table::editor()
+        ->setUnquotedName('post')
+        ->addColumn(
+            Column::editor()
+                ->setUnquotedName('id')
+                ->setTypeName('integer')
+                ->create()
+        )
+        ->addColumn(
+            Column::editor()
+                ->setUnquotedName('user_id')
+                ->setTypeName('integer')
+                ->create()
+        )
+        ->addForeignKeyConstraint(
+            ForeignKeyConstraint::editor()
+                ->setUnquotedName('fk_user_id')
+                ->setUnquotedReferencingColumnNames('user_id')
+                ->setUnquotedReferencedTableName('user')
+                ->setUnquotedReferencedColumnNames('id')
+                ->setOnUpdateAction(ReferentialAction::CASCADE)
+                ->create()
+        )
+        ->create();
+
+    $schema = new Schema([$user, $post]);
+    $schema->createSequence('my_table_seq');
+
+    $createSQL = $schema->toSql($myPlatform);     // get queries to create this schema
+    $dropSQL   = $schema->toDropSql($myPlatform); // get queries to drop this schema
 
 Now if you want to compare this schema with another schema, you can
 use the ``Comparator`` class to get instances of ``SchemaDiff``,

docs/en/reference/types.rst

@@ -210,8 +210,8 @@ Maps and converts a string which is one of a set of predefined values. This
 type is specifically designed for MySQL and MariaDB, where it is mapped to
 the native ``ENUM`` type. For other database vendors, this type is mapped to
 a string field (``VARCHAR``) with the maximum length being the length of the
-longest value in the set. Values retrieved from the database are always
-converted to PHP's ``string`` type or ``null`` if no data is present.
+longest value in the set if none was configured. Values retrieved from the database
+are always converted to PHP's ``string`` type or ``null`` if no data is present.
 
 Binary string types
 ^^^^^^^^^^^^^^^^^^^

src/Driver/PgSQL/Statement.php

@@ -57,6 +57,10 @@ public function bindValue(int|string $param, mixed $value, ParameterType $type =
             throw UnknownParameter::new((string) $param);
         }
 
+        if ($value === null) {
+            $type = ParameterType::NULL;
+        }
+
         if ($type === ParameterType::BOOLEAN) {
             $this->parameters[$this->parameterMap[$param]]     = (bool) $value === false ? 'f' : 't';
             $this->parameterTypes[$this->parameterMap[$param]] = ParameterType::STRING;

src/Platforms/AbstractPlatform.php

@@ -226,6 +226,18 @@ public function getEnumDeclarationSQL(array $column): string
             ? max(...array_map(mb_strlen(...), $column['values']))
             : mb_strlen($column['values'][key($column['values'])]);
 
+        if (isset($column['length'])) {
+            if ($length > $column['length']) {
+                throw new InvalidArgumentException(sprintf(
+                    'Specified column length (%d) is less than the maximum length of provided values (%d).',
+                    $column['length'],
+                    $length,
+                ));
+            }
+
+            $length = $column['length'];
+        }
+
         return $this->getStringTypeDeclarationSQL(['length' => $length]);
     }
 

tests/Functional/BooleanBindingTest.php

@@ -26,6 +26,7 @@ protected function setUp(): void
                 Column::editor()
                     ->setUnquotedName('val')
                     ->setTypeName(Types::BOOLEAN)
+                    ->setNotNull(false)
                     ->create(),
             )
             ->create();
@@ -39,7 +40,7 @@ protected function tearDown(): void
     }
 
     #[DataProvider('booleanProvider')]
-    public function testBooleanInsert(bool $input): void
+    public function testBooleanParameterInsert(?bool $input): void
     {
         $queryBuilder = $this->connection->createQueryBuilder();
 
@@ -48,11 +49,37 @@ public function testBooleanInsert(bool $input): void
         ])->executeStatement();
 
         self::assertSame(1, $result);
+
+        self::assertSame($input, $this->connection->convertToPHPValue(
+            $this->connection->fetchOne('SELECT val FROM boolean_test_table'),
+            Types::BOOLEAN,
+        ));
+    }
+
+    #[DataProvider('booleanProvider')]
+    public function testBooleanTypeInsert(?bool $input): void
+    {
+        $queryBuilder = $this->connection->createQueryBuilder();
+
+        $result = $queryBuilder->insert('boolean_test_table')->values([
+            'val' => $queryBuilder->createNamedParameter($input, Types::BOOLEAN),
+        ])->executeStatement();
+
+        self::assertSame(1, $result);
+
+        self::assertSame($input, $this->connection->convertToPHPValue(
+            $this->connection->fetchOne('SELECT val FROM boolean_test_table'),
+            Types::BOOLEAN,
+        ));
     }
 
-    /** @return bool[][] */
+    /** @return array<string, array{bool|null}> */
     public static function booleanProvider(): array
     {
-        return [[true], [false]];
+        return [
+            'true' => [true],
+            'false' => [false],
+            'null' => [null],
+        ];
     }
 }

tests/Platforms/AbstractMySQLPlatformTestCase.php

@@ -20,6 +20,7 @@
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types\Types;
+use PHPUnit\Framework\Attributes\DataProvider;
 
 use function array_shift;
 
@@ -594,6 +595,13 @@ protected function createComparator(): Comparator
         );
     }
 
+    /** @param array<string> $values */
+    #[DataProvider('getEnumDeclarationExceptionWithLengthSQLProvider')]
+    public function testGetEnumDeclarationExceptionWithLengthSQL(array $values, int $length): void
+    {
+        self::markTestSkipped('There is no exception thrown on MySQL.');
+    }
+
     /** @return array<string, array{array<string>, string}> */
     public static function getEnumDeclarationSQLProvider(): array
     {
@@ -602,4 +610,15 @@ public static function getEnumDeclarationSQLProvider(): array
             'multiple values' => [['foo', 'bar1'], "ENUM('foo', 'bar1')"],
         ];
     }
+
+    /** @return array<string, array{array<string>, int, string}> */
+    public static function getEnumDeclarationWithLengthSQLProvider(): array
+    {
+        return [
+            'single value and bigger length' => [['foo'], 42, "ENUM('foo')"],
+            'single value and lower length' => [['foo'], 1, "ENUM('foo')"],
+            'multiple values and bigger length' => [['foo', 'bar1'], 42, "ENUM('foo', 'bar1')"],
+            'multiple values and lower length' => [['foo', 'bar1'], 2, "ENUM('foo', 'bar1')"],
+        ];
+    }
 }

tests/Platforms/AbstractPlatformTestCase.php

@@ -5,6 +5,7 @@
 namespace Doctrine\DBAL\Tests\Platforms;
 
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\InvalidArgumentException;
 use Doctrine\DBAL\Exception\InvalidColumnDeclaration;
 use Doctrine\DBAL\Exception\InvalidColumnType\ColumnValuesRequired;
 use Doctrine\DBAL\Platforms\AbstractMySQLPlatform;
@@ -1047,6 +1048,48 @@ public static function getEnumDeclarationSQLProvider(): array
         ];
     }
 
+    /** @param array<string> $values */
+    #[DataProvider('getEnumDeclarationWithLengthSQLProvider')]
+    public function testGetEnumDeclarationWithLengthSQL(array $values, int $length, string $expectedSQL): void
+    {
+        $result = $this->platform->getEnumDeclarationSQL([
+            'values' => $values,
+            'length' => $length,
+        ]);
+
+        self::assertSame($expectedSQL, $result);
+    }
+
+    /** @param array<string> $values */
+    #[DataProvider('getEnumDeclarationExceptionWithLengthSQLProvider')]
+    public function testGetEnumDeclarationExceptionWithLengthSQL(array $values, int $length): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        $this->platform->getEnumDeclarationSQL([
+            'values' => $values,
+            'length' => $length,
+        ]);
+    }
+
+    /** @return array<string, array{array<string>, int, string}> */
+    public static function getEnumDeclarationWithLengthSQLProvider(): array
+    {
+        return [
+            'single value and bigger length' => [['foo'], 42, 'VARCHAR(42)'],
+            'multiple values and bigger length' => [['foo', 'bar1'], 42, 'VARCHAR(42)'],
+        ];
+    }
+
+    /** @return array<string, array{array<string>, int}> */
+    public static function getEnumDeclarationExceptionWithLengthSQLProvider(): array
+    {
+        return [
+            'single value and lower length' => [['foo'], 1],
+            'multiple values and lower length' => [['foo', 'bar1'], 2],
+        ];
+    }
+
     /** @param array<mixed> $column */
     #[DataProvider('getEnumDeclarationSQLWithInvalidValuesProvider')]
     public function testGetEnumDeclarationSQLWithInvalidValues(array $column): void

tests/Platforms/OraclePlatformTest.php

@@ -597,4 +597,13 @@ public static function getEnumDeclarationSQLProvider(): array
             'multiple values' => [['foo', 'bar1'], 'VARCHAR2(4)'],
         ];
     }
+
+    /** @return array<string, array{array<string>, int, string}> */
+    public static function getEnumDeclarationWithLengthSQLProvider(): array
+    {
+        return [
+            'single value and bigger length' => [['foo'], 42, 'VARCHAR2(42)'],
+            'multiple values and bigger length' => [['foo', 'bar1'], 42, 'VARCHAR2(42)'],
+        ];
+    }
 }

tests/Platforms/SQLServerPlatformTest.php

@@ -1189,4 +1189,13 @@ public static function getEnumDeclarationSQLProvider(): array
             'multiple values' => [['foo', 'bar1'], 'NVARCHAR(4)'],
         ];
     }
+
+    /** @return array<string, array{array<string>, int, string}> */
+    public static function getEnumDeclarationWithLengthSQLProvider(): array
+    {
+        return [
+            'single value and bigger length' => [['foo'], 42, 'NVARCHAR(42)'],
+            'multiple values and bigger length' => [['foo', 'bar1'], 42, 'NVARCHAR(42)'],
+        ];
+    }
 }