Merge pull request #6945 from morozov/column-editor

Deprecate Column features and introduce ColumnEditor

Author: morozov

UPGRADE.md

@@ -8,6 +8,19 @@ awareness about deprecated code.
 
 # Upgrade to 4.3
 
+## Deprecated `Column` methods
+
+The following `Column` methods have been deprecated:
+
+- `Column::getPlatformOptions()`, `Column::hasPlatformOption()`, `Column::getPlatformOption()` – use
+  `Column::getCharset()`, `Column::getCollation()`, `Column::getMinimumValue()` and `Column::getMaximumValue()`
+   instead.
+
+Additionally,
+1. Extending the `Column` class has been deprecated. Use the `Column` class directly.
+2. The `Column` constructor has been marked as internal. Use `Column::editor()` to instantiate an
+   editor and `ColumnEditor::create()` to create a column.
+
 ## The `jsonb` column platform option has been deprecated
 
 The `jsonb` column platform option has been deprecated. To define a `JSONB` column, use the `JSONB` type instead.

src/Platforms/MySQL/CharsetMetadataProvider.php

@@ -7,5 +7,6 @@
 /** @internal */
 interface CharsetMetadataProvider
 {
+    /** @return ?non-empty-string */
     public function getDefaultCharsetCollation(string $charset): ?string;
 }

src/Platforms/MySQL/CharsetMetadataProvider/CachingCharsetMetadataProvider.php

@@ -11,7 +11,7 @@
 /** @internal */
 final class CachingCharsetMetadataProvider implements CharsetMetadataProvider
 {
-    /** @var array<string,?string> */
+    /** @var array<string,?non-empty-string> */
     private array $cache = [];
 
     public function __construct(private readonly CharsetMetadataProvider $charsetMetadataProvider)

src/Platforms/MySQL/CollationMetadataProvider.php

@@ -7,5 +7,10 @@
 /** @internal */
 interface CollationMetadataProvider
 {
+    /**
+     * @param non-empty-string $collation
+     *
+     * @return ?non-empty-string
+     */
     public function getCollationCharset(string $collation): ?string;
 }

src/Platforms/MySQL/CollationMetadataProvider/CachingCollationMetadataProvider.php

@@ -11,7 +11,7 @@
 /** @internal */
 final class CachingCollationMetadataProvider implements CollationMetadataProvider
 {
-    /** @var array<string,?string> */
+    /** @var array<non-empty-string,?non-empty-string> */
     private array $cache = [];
 
     public function __construct(private readonly CollationMetadataProvider $collationMetadataProvider)

src/Schema/Column.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\DBAL\Schema;
 
+use Doctrine\DBAL\Platforms\SQLServerPlatform;
 use Doctrine\DBAL\Schema\Exception\UnknownColumnOption;
 use Doctrine\DBAL\Schema\Name\Parser\UnqualifiedNameParser;
 use Doctrine\DBAL\Schema\Name\Parsers;
@@ -17,22 +18,23 @@
 /**
  * Object representation of a database column.
  *
+ * @final
  * @extends AbstractNamedObject<UnqualifiedName>
  * @phpstan-type ColumnProperties = array{
  *     name: string,
  *     type: Type,
  *     default: mixed,
  *     notnull?: bool,
  *     autoincrement: bool,
- *     columnDefinition: ?string,
+ *     columnDefinition: ?non-empty-string,
  *     comment: string,
- *     charset?: ?string,
- *     collation?: ?string,
+ *     charset?: ?non-empty-string,
+ *     collation?: ?non-empty-string,
  * }
  * @phpstan-type PlatformOptions = array{
- *     charset?: ?string,
- *     collation?: ?string,
- *     default_constraint_name?: string,
+ *     charset?: ?non-empty-string,
+ *     collation?: ?non-empty-string,
+ *     default_constraint_name?: non-empty-string,
  *     jsonb?: bool,
  *     version?: bool,
  * }
@@ -63,12 +65,14 @@ class Column extends AbstractNamedObject
     /** @var PlatformOptions */
     protected array $_platformOptions = [];
 
+    /** @var ?non-empty-string */
     protected ?string $_columnDefinition = null;
 
     protected string $_comment = '';
 
     /**
-     * Creates a new Column.
+     * @internal Use {@link Column::editor()} to instantiate an editor and {@link ColumnEditor::create()} to create a
+     *           column.
      *
      * @param array<string, mixed> $options
      */
@@ -189,6 +193,7 @@ public function setPlatformOption(string $name, mixed $value): self
         return $this;
     }
 
+    /** @param  ?non-empty-string $value */
     public function setColumnDefinition(?string $value): self
     {
         $this->_columnDefinition = $value;
@@ -236,19 +241,82 @@ public function getDefault(): mixed
         return $this->_default;
     }
 
-    /** @return PlatformOptions */
+    /**
+     * Returns the name of the character set to use with the column.
+     *
+     * @return ?non-empty-string
+     */
+    public function getCharset(): ?string
+    {
+        return $this->_platformOptions['charset'] ?? null;
+    }
+
+    /**
+     * Returns the name of the collation to use with the column.
+     *
+     * @return ?non-empty-string
+     */
+    public function getCollation(): ?string
+    {
+        return $this->_platformOptions['collation'] ?? null;
+    }
+
+    /**
+     * Returns the minimum value to enforce on the column.
+     */
+    public function getMinimumValue(): mixed
+    {
+        return $this->_platformOptions['min'] ?? null;
+    }
+
+    /**
+     * Returns the maximum value to enforce on the column.
+     */
+    public function getMaximumValue(): mixed
+    {
+        return $this->_platformOptions['max'] ?? null;
+    }
+
+    /**
+     * @internal Should be used only from within the {@see AbstractSchemaManager} class hierarchy.
+     *
+     * Returns the name of the DEFAULT constraint that implements the default value for the column on SQL Server.
+     *
+     * @return ?non-empty-string
+     */
+    public function getDefaultConstraintName(): ?string
+    {
+        return $this->_platformOptions[SQLServerPlatform::OPTION_DEFAULT_CONSTRAINT_NAME] ?? null;
+    }
+
+    /**
+     * @deprecated Use {@see getCharset()}, {@see getCollation()}, {@see getMinimumValue()} or {@see getMaximumValue()}
+     *             instead.
+     *
+     * @return PlatformOptions
+     */
     public function getPlatformOptions(): array
     {
         return $this->_platformOptions;
     }
 
-    /** @param key-of<PlatformOptions> $name */
+    /**
+     * @deprecated Use {@see getCharset()}, {@see getCollation()}, {@see getMinimumValue()} or {@see getMaximumValue()}
+     *             instead.
+     *
+     * @param key-of<PlatformOptions> $name
+     */
     public function hasPlatformOption(string $name): bool
     {
         return isset($this->_platformOptions[$name]);
     }
 
-    /** @param key-of<PlatformOptions> $name */
+    /**
+     * @deprecated Use {@see getCharset()}, {@see getCollation()}, {@see getMinimumValue()} or {@see getMaximumValue()}
+     *             instead.
+     *
+     * @param key-of<PlatformOptions> $name
+     */
     public function getPlatformOption(string $name): mixed
     {
         /** @phpstan-ignore offsetAccess.notFound */
@@ -321,4 +389,32 @@ public function toArray(): array
             'values'           => $this->_values,
         ], $this->_platformOptions);
     }
+
+    public static function editor(): ColumnEditor
+    {
+        return new ColumnEditor();
+    }
+
+    public function edit(): ColumnEditor
+    {
+        return self::editor()
+            ->setName($this->getObjectName())
+            ->setType($this->_type)
+            ->setLength($this->_length)
+            ->setPrecision($this->_precision)
+            ->setScale($this->_scale)
+            ->setUnsigned($this->_unsigned)
+            ->setFixed($this->_fixed)
+            ->setNotNull($this->_notnull)
+            ->setDefaultValue($this->_default)
+            ->setAutoincrement($this->_autoincrement)
+            ->setComment($this->_comment)
+            ->setValues($this->_values)
+            ->setColumnDefinition($this->_columnDefinition)
+            ->setCharset($this->getCharset())
+            ->setCollation($this->getCollation())
+            ->setMinimumValue($this->getMinimumValue())
+            ->setMaximumValue($this->getMaximumValue())
+            ->setDefaultConstraintName($this->getDefaultConstraintName());
+    }
 }