Introduce UniqueConstraintEditor

doctrine · Jan 5, 2025 · a0dfb21 · a0dfb21
1 parent 08e62ad
commit a0dfb21
Show file tree

Hide file tree

Showing 10 changed files with 193 additions and 22 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -25,7 +25,9 @@ The following `UniqueConstraint` methods and property have been deprecated:
 Additionally,
 1. Extending the `UniqueConstraint` class has been deprecated. Use the `UniqueConstraint` class directly.
 2. Instantiation of a unique constraint without columns is deprecated.
-3. The `AbstractPlatform::getUniqueConstraintDeclarationSQL()` method has been marked as internal.
+3. The `UniqueConstraint` constructor has been marked as internal. Use `UniqueConstraint::editor()` to instantiate an
+   editor and `UniqueConstraintEditor::create()` to create a unique constraint.
+4. The `AbstractPlatform::getUniqueConstraintDeclarationSQL()` method has been marked as internal.
 
 ## Deprecated `AbstractAsset::isIdentifierQuoted()`
 

diff --git a/src/Schema/Exception/InvalidUniqueConstraintDefinition.php b/src/Schema/Exception/InvalidUniqueConstraintDefinition.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema\Exception;
+
+use Doctrine\DBAL\Schema\SchemaException;
+use LogicException;
+
+/** @psalm-immutable */
+final class InvalidUniqueConstraintDefinition extends LogicException implements SchemaException
+{
+    public static function columnNamesAreNotSet(): self
+    {
+        return new self('Unique constraint column names are not set.');
+    }
+}
diff --git a/src/Schema/UniqueConstraint.php b/src/Schema/UniqueConstraint.php
@@ -53,6 +53,9 @@ class UniqueConstraint extends AbstractOptionallyNamedObject
     private bool $failedToParseColumnNames = false;
 
     /**
+     * @internal Use {@link UniqueConstraint::editor()} to instantiate an editor and
+     *           {@link UniqueConstraintEditor::create()} to create a unique constraint.
+     *
      * @param non-empty-list<string> $columns
      * @param array<string>          $flags
      * @param array<string, mixed>   $options
@@ -201,7 +204,7 @@ public function getFlags(): array
     /**
      * Adds flag for a unique constraint that translates to platform specific handling.
      *
-     * @deprecated
+     * @deprecated Use {@see UniqueConstraintEditor::setIsClustered()} instead.
      *
      * @return $this
      *
@@ -249,7 +252,7 @@ public function isClustered(): bool
     /**
      * Removes a flag.
      *
-     * @deprecated
+     * @deprecated Use {@see UniqueConstraintEditor::setIsClustered()} instead.
      */
     public function removeFlag(string $flag): void
     {
@@ -333,4 +336,23 @@ protected function addColumn(string $column): void
             );
         }
     }
+
+    /**
+     * Instantiates a new unique constraint editor.
+     */
+    public static function editor(): UniqueConstraintEditor
+    {
+        return new UniqueConstraintEditor();
+    }
+
+    /**
+     * Instantiates a new unique constraint editor and initializes it with the constraint's properties.
+     */
+    public function edit(): UniqueConstraintEditor
+    {
+        return self::editor()
+            ->setName($this->getObjectName())
+            ->setColumnNames(...$this->getColumnNames())
+            ->setIsClustered($this->isClustered());
+    }
 }
diff --git a/src/Schema/UniqueConstraintEditor.php b/src/Schema/UniqueConstraintEditor.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema;
+
+use Doctrine\DBAL\Schema\Exception\InvalidUniqueConstraintDefinition;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
+
+use function array_map;
+use function array_merge;
+use function array_values;
+use function count;
+
+final class UniqueConstraintEditor
+{
+    private ?UnqualifiedName $name = null;
+
+    /** @var list<UnqualifiedName> */
+    private array $columnNames = [];
+
+    private bool $isClustered = false;
+
+    /** @internal Use {@link UniqueConstraint::editor()} or {@link UniqueConstraint::edit()} to create an instance */
+    public function __construct()
+    {
+    }
+
+    public function setName(?UnqualifiedName $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function setColumnNames(UnqualifiedName $firstColumName, UnqualifiedName ...$otherColumnNames): self
+    {
+        $this->columnNames = array_merge([$firstColumName], array_values($otherColumnNames));
+
+        return $this;
+    }
+
+    public function setIsClustered(bool $isClustered): self
+    {
+        $this->isClustered = $isClustered;
+
+        return $this;
+    }
+
+    public function create(): UniqueConstraint
+    {
+        if (count($this->columnNames) < 1) {
+            throw InvalidUniqueConstraintDefinition::columnNamesAreNotSet();
+        }
+
+        return new UniqueConstraint(
+            $this->name?->toString() ?? '',
+            array_map(static fn (UnqualifiedName $columnName) => $columnName->toString(), $this->columnNames),
+            $this->isClustered ? ['clustered'] : [],
+        );
+    }
+}
diff --git a/tests/Functional/Schema/SchemaManagerFunctionalTestCase.php b/tests/Functional/Schema/SchemaManagerFunctionalTestCase.php
@@ -12,7 +12,9 @@
 use Doctrine\DBAL\Schema\AbstractAsset;
 use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\ForeignKeyConstraint;
+use Doctrine\DBAL\Schema\Name\Identifier;
 use Doctrine\DBAL\Schema\Name\OptionallyQualifiedName;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Schema;
 use Doctrine\DBAL\Schema\SchemaDiff;
 use Doctrine\DBAL\Schema\SchemaException;
@@ -435,7 +437,15 @@ public function testDropAndCreateUniqueConstraint(): void
         $table->addColumn('id', Types::INTEGER);
         $this->dropAndCreateTable($table);
 
-        $uniqueConstraint = new UniqueConstraint('uniq_id', ['id']);
+        $uniqueConstraint = UniqueConstraint::editor()
+            ->setName(
+                new UnqualifiedName(Identifier::unquoted('uniq_id')),
+            )
+            ->setColumnNames(
+                new UnqualifiedName(Identifier::unquoted('id')),
+            )
+            ->create();
+
         $this->schemaManager->createUniqueConstraint($uniqueConstraint, $table->getName());
 
         // there's currently no API for introspecting unique constraints,

diff --git a/tests/Functional/Schema/UniqueConstraintTest.php b/tests/Functional/Schema/UniqueConstraintTest.php
@@ -5,6 +5,8 @@
 namespace Doctrine\DBAL\Tests\Functional\Schema;
 
 use Doctrine\DBAL\Schema\Column;
+use Doctrine\DBAL\Schema\Name\Identifier;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\UniqueConstraint;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
@@ -22,8 +24,12 @@ public function testUnnamedUniqueConstraint(): void
             new Column('username', Type::getType(Types::STRING), ['length' => 32]),
             new Column('email', Type::getType(Types::STRING), ['length' => 255]),
         ], [], [
-            new UniqueConstraint('', ['username']),
-            new UniqueConstraint('', ['email']),
+            UniqueConstraint::editor()
+                ->setColumnNames(new UnqualifiedName(Identifier::unquoted('username')))
+                ->create(),
+            UniqueConstraint::editor()
+                ->setColumnNames(new UnqualifiedName(Identifier::unquoted('email')))
+                ->create(),
         ], []);
 
         $sm = $this->connection->createSchemaManager();

diff --git a/tests/Functional/UniqueConstraintViolationsTest.php b/tests/Functional/UniqueConstraintViolationsTest.php
@@ -13,6 +13,8 @@
 use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
 use Doctrine\DBAL\Platforms\SQLitePlatform;
 use Doctrine\DBAL\Platforms\SQLServerPlatform;
+use Doctrine\DBAL\Schema\Name\Identifier;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\UniqueConstraint;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
@@ -33,8 +35,6 @@ protected function setUp(): void
 
         if ($platform instanceof OraclePlatform) {
             $constraintName = 'C1_UNIQUE';
-        } elseif ($platform instanceof PostgreSQLPlatform) {
-            $constraintName = 'c1_unique';
         } else {
             $constraintName = 'c1_unique';
         }
@@ -47,13 +47,7 @@ protected function setUp(): void
         $table->addColumn('unique_field', 'integer', ['notnull' => true]);
         $schemaManager->createTable($table);
 
-        if ($platform instanceof OraclePlatform) {
-            $createConstraint = sprintf(
-                'ALTER TABLE unique_constraint_violations ' .
-                'ADD CONSTRAINT %s UNIQUE (unique_field) DEFERRABLE INITIALLY IMMEDIATE',
-                $constraintName,
-            );
-        } elseif ($platform instanceof PostgreSQLPlatform) {
+        if ($platform instanceof OraclePlatform || $platform instanceof PostgreSQLPlatform) {
             $createConstraint = sprintf(
                 'ALTER TABLE unique_constraint_violations ' .
                 'ADD CONSTRAINT %s UNIQUE (unique_field) DEFERRABLE INITIALLY IMMEDIATE',
@@ -65,7 +59,10 @@ protected function setUp(): void
                 $constraintName,
             );
         } else {
-            $createConstraint = new UniqueConstraint($constraintName, ['unique_field']);
+            $createConstraint = UniqueConstraint::editor()
+                ->setName(new UnqualifiedName(Identifier::unquoted($constraintName)))
+                ->setColumnNames(new UnqualifiedName(Identifier::unquoted('unique_field')))
+                ->create();
         }
 
         if ($createConstraint instanceof UniqueConstraint) {

diff --git a/tests/Platforms/AbstractPlatformTestCase.php b/tests/Platforms/AbstractPlatformTestCase.php
@@ -14,6 +14,8 @@
 use Doctrine\DBAL\Schema\ComparatorConfig;
 use Doctrine\DBAL\Schema\ForeignKeyConstraint;
 use Doctrine\DBAL\Schema\Index;
+use Doctrine\DBAL\Schema\Name\Identifier;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\Schema\UniqueConstraint;
@@ -188,7 +190,13 @@ public function testGeneratesPartialIndexesSqlOnlyWhenSupportingPartialIndexes()
     {
         $where            = 'test IS NULL AND test2 IS NOT NULL';
         $indexDef         = new Index('name', ['test', 'test2'], false, false, [], ['where' => $where]);
-        $uniqueConstraint = new UniqueConstraint('name', ['test', 'test2'], [], []);
+        $uniqueConstraint = UniqueConstraint::editor()
+            ->setName(new UnqualifiedName(Identifier::unquoted('name')))
+            ->setColumnNames(
+                new UnqualifiedName(Identifier::unquoted('test')),
+                new UnqualifiedName(Identifier::unquoted('test2')),
+            )
+            ->create();
 
         $expected = ' WHERE ' . $where;
 

diff --git a/tests/Schema/UniqueConstraintEditorTest.php b/tests/Schema/UniqueConstraintEditorTest.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Schema;
+
+use Doctrine\DBAL\Schema\Exception\InvalidUniqueConstraintDefinition;
+use Doctrine\DBAL\Schema\Name\Identifier;
+use Doctrine\DBAL\Schema\Name\UnqualifiedName;
+use Doctrine\DBAL\Schema\UniqueConstraint;
+use PHPUnit\Framework\TestCase;
+
+class UniqueConstraintEditorTest extends TestCase
+{
+    public function testEmptyColumnNames(): void
+    {
+        $this->expectException(InvalidUniqueConstraintDefinition::class);
+
+        UniqueConstraint::editor()
+            ->create();
+    }
+
+    public function testSetIsClustered(): void
+    {
+        $columnName = new UnqualifiedName(Identifier::unquoted('user_id'));
+
+        $editor = UniqueConstraint::editor()
+            ->setColumnNames($columnName);
+
+        $constraint = $editor->create();
+        self::assertFalse($constraint->isClustered());
+
+        $constraint = $editor
+            ->setIsClustered(true)
+            ->create();
+        self::assertTrue($constraint->isClustered());
+    }
+}
diff --git a/tests/Schema/UniqueConstraintTest.php b/tests/Schema/UniqueConstraintTest.php
@@ -20,17 +20,26 @@ class UniqueConstraintTest extends TestCase
     /** @throws Exception */
     public function testGetNonNullObjectName(): void
     {
-        $uniqueConstraint = new UniqueConstraint('uq_user_id', ['user_id']);
-        $name             = $uniqueConstraint->getObjectName();
+        $name = new UnqualifiedName(Identifier::unquoted('uq_user_id'));
 
-        self::assertNotNull($name);
-        self::assertEquals(Identifier::unquoted('uq_user_id'), $name->getIdentifier());
+        $uniqueConstraint = UniqueConstraint::editor()
+            ->setName($name)
+            ->setColumnNames(
+                new UnqualifiedName(Identifier::unquoted('user_id')),
+            )
+            ->create();
+
+        self::assertEquals($name, $uniqueConstraint->getObjectName());
     }
 
     /** @throws Exception */
     public function testGetNullObjectName(): void
     {
-        $uniqueConstraint = new UniqueConstraint('', ['user_id']);
+        $uniqueConstraint = UniqueConstraint::editor()
+            ->setColumnNames(
+                new UnqualifiedName(Identifier::unquoted('user_id')),
+            )
+            ->create();
 
         self::assertNull($uniqueConstraint->getObjectName());
     }