Add ENUM column (#1107)

Co-authored-by: Sergei Tigrov <[email protected]>

Author: vjik

CHANGELOG.md

@@ -178,6 +178,7 @@
 - Chg #1103: Remove `AbstractCommand::refreshTableSchema()` method (@vjik)
 - Chg #1106: Remove parameters from `PdoConnectionInterface::getActivePdo()` method (@vjik)
 - Bug #1109: Fix column definition parsing in cases with brackets and escaped quotes (@vjik)
+- New #1107: Add abstract enumeration column type (@vjik)
 
 ## 1.3.0 March 21, 2024
 

src/Constant/ColumnType.php

@@ -105,4 +105,8 @@ final class ColumnType
      * Define the abstract column type as `json`.
      */
     public const JSON = 'json';
+    /**
+     * Define the abstract column type as `enum`.
+     */
+    public const ENUM = 'enum';
 }

src/QueryBuilder/AbstractColumnDefinitionBuilder.php

@@ -8,6 +8,7 @@
 use Yiisoft\Db\Constant\ReferentialAction;
 use Yiisoft\Db\Schema\Column\CollatableColumnInterface;
 use Yiisoft\Db\Schema\Column\ColumnInterface;
+use Yiisoft\Db\Schema\Column\EnumColumn;
 
 use function in_array;
 use function strtolower;
@@ -122,6 +123,25 @@ protected function buildCheck(ColumnInterface $column): string
     {
         $check = $column->getCheck();
 
+        if (empty($check)
+            && $column instanceof EnumColumn
+            && $column->getDbType() === null
+        ) {
+            $name = $column->getName();
+            if (!empty($name)) {
+                $quoter = $this->queryBuilder->getQuoter();
+                $quotedItems = implode(
+                    ',',
+                    array_map(
+                        $quoter->quoteValue(...),
+                        $column->getValues(),
+                    ),
+                );
+                $quotedName = $quoter->quoteColumnName($name);
+                $check = "$quotedName IN ($quotedItems)";
+            }
+        }
+
         return !empty($check) ? " CHECK ($check)" : '';
     }
 

src/Schema/Column/AbstractColumn.php

@@ -61,7 +61,6 @@ abstract class AbstractColumn implements ColumnInterface
      * @param string|null $comment The column's comment.
      * @param bool $computed Whether the column is a computed column.
      * @param string|null $dbType The column's database type.
-     * @param array|null $enumValues The list of possible values for an ENUM column.
      * @param string|null $extra Any extra information that needs to be appended to the column's definition.
      * @param bool $primaryKey Whether the column is a primary key.
      * @param string|null $name The column's name.
@@ -83,7 +82,6 @@ public function __construct(
         private ?string $comment = null,
         private bool $computed = false,
         private ?string $dbType = null,
-        private ?array $enumValues = null,
         private ?string $extra = null,
         private bool $primaryKey = false,
         private ?string $name = null,
@@ -146,12 +144,6 @@ public function defaultValue(mixed $defaultValue): static
         return $this;
     }
 
-    public function enumValues(?array $enumValues): static
-    {
-        $this->enumValues = $enumValues;
-        return $this;
-    }
-
     public function extra(?string $extra): static
     {
         $this->extra = $extra;
@@ -182,12 +174,6 @@ public function getDefaultValue(): mixed
         return $this->defaultValue ?? null;
     }
 
-    /** @psalm-mutation-free */
-    public function getEnumValues(): ?array
-    {
-        return $this->enumValues;
-    }
-
     /** @psalm-mutation-free */
     public function getExtra(): ?string
     {

src/Schema/Column/AbstractColumnFactory.php

@@ -256,6 +256,7 @@ protected function getColumnClass(string $type, array $info = []): string
             ColumnType::ARRAY => ArrayColumn::class,
             ColumnType::STRUCTURED => StructuredColumn::class,
             ColumnType::JSON => JsonColumn::class,
+            ColumnType::ENUM => EnumColumn::class,
             default => StringColumn::class,
         };
     }
@@ -277,6 +278,10 @@ protected function getType(string $dbType, array $info = []): string
             return ColumnType::ARRAY;
         }
 
+        if (isset($info['values'])) {
+            return ColumnType::ENUM;
+        }
+
         return static::TYPE_MAP[$dbType] ?? ColumnType::STRING;
     }
 
@@ -333,7 +338,8 @@ protected function isType(string $type): bool
             ColumnType::DATE,
             ColumnType::ARRAY,
             ColumnType::STRUCTURED,
-            ColumnType::JSON => true,
+            ColumnType::JSON,
+            ColumnType::ENUM => true,
             default => isset($this->classMap[$type]),
         };
     }

src/Schema/Column/ColumnBuilder.php

@@ -271,4 +271,15 @@ public static function json(): ColumnInterface
     {
         return new JsonColumn(ColumnType::JSON);
     }
+
+    /**
+     * Builds a column with the abstract type `enum`.
+     *
+     * @param string[]|null $values The list of possible values for the enum column.
+     * @param string|null $dbType The database type of the column. When null, the column will use a CHECK constraint.
+     */
+    public static function enum(?array $values = null, ?string $dbType = null): EnumColumn
+    {
+        return new EnumColumn(dbType: $dbType, values: $values);
+    }
 }

src/Schema/Column/ColumnFactoryInterface.php

@@ -25,7 +25,6 @@
  *     defaultValue?: mixed,
  *     defaultValueRaw?: string|null,
  *     dimension?: positive-int,
- *     enumValues?: array|null,
  *     extra?: string|null,
  *     fromResult?: bool,
  *     primaryKey?: bool,
@@ -39,6 +38,7 @@
  *     type?: ColumnType::*,
  *     unique?: bool,
  *     unsigned?: bool,
+ *     values?: array|null,
  * }
  */
 interface ColumnFactoryInterface

src/Schema/Column/ColumnInterface.php

@@ -105,17 +105,6 @@ public function dbTypecast(mixed $value): mixed;
      */
     public function defaultValue(mixed $defaultValue): static;
 
-    /**
-     * The list of possible values for the `ENUM` column.
-     *
-     * ```php
-     * $columns = [
-     *     'status' => ColumnBuilder::string(16)->enumValues(['active', 'inactive']),
-     * ];
-     * ```
-     */
-    public function enumValues(?array $enumValues): static;
-
     /**
      * Extra SQL to append to the generated SQL for a column.
      *
@@ -166,14 +155,6 @@ public function getDbType(): ?string;
      */
     public function getDefaultValue(): mixed;
 
-    /**
-     * @return array|null The enum values of the column.
-     *
-     * @see enumValues()
-     * @psalm-mutation-free
-     */
-    public function getEnumValues(): ?array;
-
     /**
      * @return string|null The extra SQL for the column.
      *

src/Schema/Column/EnumColumn.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Schema\Column;
+
+use LogicException;
+use Yiisoft\Db\Constant\ColumnType;
+
+final class EnumColumn extends StringColumn
+{
+    protected const DEFAULT_TYPE = ColumnType::ENUM;
+
+    /**
+     * @var string[]|null $values The list of possible values for an ENUM column.
+     * @psalm-var non-empty-list<string>|null
+     */
+    protected ?array $values = null;
+
+    /**
+     * @param string[] $values The list of possible values for the `ENUM` column.
+     * @psalm-param non-empty-list<string> $values
+     */
+    public function values(array $values): static
+    {
+        $this->values = $values;
+        return $this;
+    }
+
+    /**
+     * @return string[] The enum values of the column.
+     * @psalm-return non-empty-list<string>
+     *
+     * @see values()
+     */
+    public function getValues(): array
+    {
+        if ($this->values === null) {
+            throw new LogicException('Enum values have not been set.');
+        }
+        return $this->values;
+    }
+}

src/Syntax/ColumnDefinitionParser.php

@@ -44,14 +44,14 @@ class ColumnDefinitionParser
      *     comment?: string,
      *     defaultValueRaw?: string,
      *     dimension?: positive-int,
-     *     enumValues?: list<string>,
      *     extra?: string,
      *     notNull?: bool,
      *     scale?: int,
      *     size?: int,
      *     type: lowercase-string,
      *     unique?: bool,
      *     unsigned?: bool,
+     *     values?: list<string>,
      * }
      */
     public function parse(string $definition): array
@@ -80,7 +80,7 @@ public function parse(string $definition): array
     }
 
     /**
-     * @psalm-return array{enumValues: list<string>}
+     * @psalm-return array{values: list<string>}
      */
     protected function enumInfo(string $values): array
     {
@@ -91,7 +91,7 @@ protected function enumInfo(string $values): array
             $matches[1],
         );
 
-        return ['enumValues' => $values];
+        return ['values' => $values];
     }
 
     /**