Introduce view editor

Author: morozov

UPGRADE.md

@@ -8,6 +8,11 @@ awareness about deprecated code.
 
 # Upgrade to 4.4
 
+## Deprecated `View` features
+
+The `View` constructor has been marked as internal. Use `View::editor()` to instantiate an editor and
+`ViewEditor::create()` to create a view.
+
 ## Deprecated `Sequence` features
 
 1. The `Sequence` constructor has been marked as internal. Use `Sequence::editor()` to instantiate an editor and

src/Schema/Exception/InvalidViewDefinition.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema\Exception;
+
+use Doctrine\DBAL\Schema\Name\OptionallyQualifiedName;
+use Doctrine\DBAL\Schema\SchemaException;
+use LogicException;
+
+use function sprintf;
+
+final class InvalidViewDefinition extends LogicException implements SchemaException
+{
+    public static function nameNotSet(): self
+    {
+        return new self('View name is not set.');
+    }
+
+    public static function sqlNotSet(OptionallyQualifiedName $viewName): self
+    {
+        return new self(sprintf('SQL is not set for view %s.', $viewName->toString()));
+    }
+}

src/Schema/View.php

@@ -16,6 +16,7 @@
  */
 class View extends AbstractNamedObject
 {
+    /** @internal Use {@link View::editor()} to instantiate an editor and {@link ViewEditor::create()} to create a view. */
     public function __construct(string $name, private readonly string $sql)
     {
         parent::__construct($name);
@@ -30,4 +31,22 @@ public function getSql(): string
     {
         return $this->sql;
     }
+
+    /**
+     * Instantiates a new view editor.
+     */
+    public static function editor(): ViewEditor
+    {
+        return new ViewEditor();
+    }
+
+    /**
+     * Instantiates a new view editor and initializes it with the view's properties.
+     */
+    public function edit(): ViewEditor
+    {
+        return self::editor()
+            ->setName($this->getObjectName())
+            ->setSQL($this->sql);
+    }
 }

src/Schema/ViewEditor.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema;
+
+use Doctrine\DBAL\Schema\Exception\InvalidViewDefinition;
+use Doctrine\DBAL\Schema\Name\OptionallyQualifiedName;
+
+final class ViewEditor
+{
+    private ?OptionallyQualifiedName $name = null;
+
+    private ?string $sql = null;
+
+    /** @internal Use {@link View::editor()} or {@link View::edit()} to create an instance */
+    public function __construct()
+    {
+    }
+
+    public function setName(OptionallyQualifiedName $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string  $unqualifiedName
+     * @param ?non-empty-string $qualifier
+     */
+    public function setUnquotedName(string $unqualifiedName, ?string $qualifier = null): self
+    {
+        $this->name = OptionallyQualifiedName::unquoted($unqualifiedName, $qualifier);
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string  $unqualifiedName
+     * @param ?non-empty-string $qualifier
+     */
+    public function setQuotedName(string $unqualifiedName, ?string $qualifier = null): self
+    {
+        $this->name = OptionallyQualifiedName::quoted($unqualifiedName, $qualifier);
+
+        return $this;
+    }
+
+    public function setSQL(string $sql): self
+    {
+        $this->sql = $sql;
+
+        return $this;
+    }
+
+    public function create(): View
+    {
+        if ($this->name === null) {
+            throw InvalidViewDefinition::nameNotSet();
+        }
+
+        if ($this->sql === null) {
+            throw InvalidViewDefinition::sqlNotSet($this->name);
+        }
+
+        return new View(
+            $this->name->toString(),
+            $this->sql,
+        );
+    }
+}

tests/Functional/Schema/PostgreSQLSchemaManagerTest.php

@@ -408,7 +408,10 @@ public function testListTablesExcludesViews(): void
         $name = 'list_tables_excludes_views_test_view';
         $sql  = 'SELECT * from list_tables_excludes_views';
 
-        $view = new View($name, $sql);
+        $view = View::editor()
+            ->setUnquotedName($name)
+            ->setSQL($sql)
+            ->create();
 
         $this->schemaManager->createView($view);
 

tests/Functional/Schema/SchemaManagerFunctionalTestCase.php

@@ -235,7 +235,11 @@ public function testListTablesDoesNotIncludeViews(): void
 
         $sql = 'SELECT * FROM test_table_for_view';
 
-        $view = new View('test_view', $sql);
+        $view = View::editor()
+            ->setUnquotedName('test_view')
+            ->setSQL($sql)
+            ->create();
+
         $this->schemaManager->createView($view);
 
         $tables = $this->schemaManager->listTables();
@@ -788,7 +792,10 @@ public function testCreateAndListViews(): void
         $name = 'doctrine_test_view';
         $sql  = 'SELECT * FROM view_test_table';
 
-        $view = new View($name, $sql);
+        $view = View::editor()
+            ->setUnquotedName($name)
+            ->setSQL($sql)
+            ->create();
 
         $this->schemaManager->createView($view);