From 06670a6b6e887a9b86f7425027c781024dfba443 Mon Sep 17 00:00:00 2001
From: Sergei Tigrov <rrr-r@ya.ru>
Date: Mon, 10 Feb 2025 10:08:08 +0700
Subject: [PATCH] Move index type constants to `IndexType` class (#920)

---
 CHANGELOG.md                                  |  1 +
 UPGRADE.md                                    |  7 +--
 src/Command/CommandInterface.php              |  9 ++--
 src/Constant/IndexType.php                    | 17 ++++++++
 src/QueryBuilder/DDLQueryBuilderInterface.php | 10 +++--
 src/Schema/SchemaInterface.php                | 22 ++++++++++
 tests/Common/CommonCommandTest.php            | 43 ++++++++-----------
 tests/Common/CommonSchemaTest.php             |  8 ++--
 tests/Provider/CommandProvider.php            | 10 ++---
 tests/Provider/QueryBuilderProvider.php       |  6 +--
 tests/Provider/SchemaProvider.php             |  3 +-
 11 files changed, 90 insertions(+), 46 deletions(-)
 create mode 100644 src/Constant/IndexType.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fac6740e8..f909269f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -56,6 +56,7 @@
 - Enh #919: Replace `name()` with immutable `withName()` method in `ColumnInterface` interface (@Tigrov)
 - Enh #921: Move `DataType` class to `Yiisoft\Db\Constant` namespace (@Tigrov)
 - Enh #926: Refactor `DbArrayHelper` (@Tigrov)
+- Enh #920: Move index constants to the appropriate DBMS driver's `IndexType` and `IndexMethod` classes (@Tigrov) 
 
 ## 1.3.0 March 21, 2024
 
diff --git a/UPGRADE.md b/UPGRADE.md
index f581eb4d1..de51062aa 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -93,9 +93,10 @@ and the following changes were made:
 ### New classes with constants
 
 - `Yiisoft\Db\Constant\PhpType` with PHP types constants;
-- `Yiisoft\Db\Constant\GettypeResult` with `gettype()` function results constants.
-- `Yiisoft\Db\Constant\ColumnType` with abstract column types constants.
-- `Yiisoft\Db\Constant\PseudoType` with column pseudo-types constants.
+- `Yiisoft\Db\Constant\GettypeResult` with `gettype()` function results constants;
+- `Yiisoft\Db\Constant\ColumnType` with abstract column types constants;
+- `Yiisoft\Db\Constant\PseudoType` with column pseudo-types constants;
+- `Yiisoft\Db\Constant\IndexType` with table index types.
 
 ### New classes for table columns
 
diff --git a/src/Command/CommandInterface.php b/src/Command/CommandInterface.php
index 2fee9eee1..f88b469bf 100644
--- a/src/Command/CommandInterface.php
+++ b/src/Command/CommandInterface.php
@@ -10,6 +10,7 @@
 use Yiisoft\Db\Connection\ConnectionInterface;
 use Yiisoft\Db\Constant\ColumnType;
 use Yiisoft\Db\Constant\DataType;
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Constant\PseudoType;
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidArgumentException;
@@ -297,13 +298,15 @@ public function checkIntegrity(string $schema, string $table, bool $check = true
      * @param string $name The name of the index.
      * @param array|string $columns The column(s) to include in the index. If there are many columns,
      * separate them with commas.
-     * @param string|null $indexType The type of index-supported DBMS - for example: `UNIQUE`, `FULLTEXT`, `SPATIAL`,
-     * `BITMAP` or null as default.
-     * @param string|null $indexMethod The setting index organization method (with `USING`, not all DBMS).
+     * @param string|null $indexType The type of the index supported by DBMS {@see IndexType} - for example: `UNIQUE`,
+     * `FULLTEXT`, `SPATIAL`, `BITMAP` or null as default.
+     * @param string|null $indexMethod The index organization method (with `USING`, not all DBMS).
      *
      * @throws Exception
      * @throws InvalidArgumentException
      *
+     * @psalm-param IndexType::*|null $indexType
+     *
      * Note: The method will quote the `name`, `table`, and `column` parameters before using them in the generated SQL.
      */
     public function createIndex(
diff --git a/src/Constant/IndexType.php b/src/Constant/IndexType.php
new file mode 100644
index 000000000..aa03267a1
--- /dev/null
+++ b/src/Constant/IndexType.php
@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Db\Constant;
+
+/**
+ * Defines the available index types for {@see DDLQueryBuilderInterface::createIndex()} method.
+ * Use driver specific implementations for other supported types if any.
+ */
+final class IndexType
+{
+    /**
+     * Define the type of the index as `UNIQUE`.
+     */
+    public const UNIQUE = 'UNIQUE';
+}
diff --git a/src/QueryBuilder/DDLQueryBuilderInterface.php b/src/QueryBuilder/DDLQueryBuilderInterface.php
index 00b474262..ef6756062 100644
--- a/src/QueryBuilder/DDLQueryBuilderInterface.php
+++ b/src/QueryBuilder/DDLQueryBuilderInterface.php
@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Db\QueryBuilder;
 
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidArgumentException;
 use Yiisoft\Db\Exception\InvalidConfigException;
@@ -204,15 +205,18 @@ public function checkIntegrity(string $schema = '', string $table = '', bool $ch
      * @param string $name The name of the index.
      * @param array|string $columns The column(s) to include in the index.
      * If there are many columns, separate them with commas or use an array to represent them.
-     * @param string|null $indexType Type of index-supported DBMS - for example, `UNIQUE`, `FULLTEXT`, `SPATIAL`, `BITMAP` or
-     * `null` as default
-     * @param string|null $indexMethod For setting index organization method (with `USING`, not all DBMS)
+     * @param string|null $indexType The index type, `UNIQUE` or a DBMS specific index type or `null` by default.
+     * See {@see IndexType} or driver specific `IndexType` class.
+     * @param string|null $indexMethod The index organization method, if supported by DBMS.
+     * See driver specific `IndexMethod` class.
      *
      * @throws Exception
      * @throws InvalidArgumentException
      *
      * @return string The SQL statement for creating a new index.
      *
+     * @psalm-param IndexType::*|null $indexType
+     *
      * Note: The method will quote the `name`, `table`, and `column` parameters before using them in the generated SQL.
      */
     public function createIndex(
diff --git a/src/Schema/SchemaInterface.php b/src/Schema/SchemaInterface.php
index db7cc3375..4e72f46e9 100644
--- a/src/Schema/SchemaInterface.php
+++ b/src/Schema/SchemaInterface.php
@@ -58,66 +58,88 @@ interface SchemaInterface extends ConstraintSchemaInterface
      * Define the type of the index as `UNIQUE`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MySQL`, `MariaDB`, `MSSQL`, `Oracle`, `PostgreSQL`, `SQLite`.
+     *
+     * @deprecated Use {@see IndexType::UNIQUE} instead. Will be removed in 2.0.
      */
     public const INDEX_UNIQUE = 'UNIQUE';
     /**
      * Define the type of the index as `BTREE`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MySQL`, `PostgreSQL`.
+     *
+     * @deprecated Use {@see IndexType::BTREE} instead. Will be removed in 2.0.
      */
     public const INDEX_BTREE = 'BTREE';
     /**
      * Define the type of the index as `HASH`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MySQL`, `PostgreSQL`.
+     *
+     * @deprecated Use {@see IndexType::HASH} instead. Will be removed in 2.0.
      */
     public const INDEX_HASH = 'HASH';
     /**
      * Define the type of the index as `FULLTEXT`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MySQL`.
+     *
+     * @deprecated Use {@see IndexType::FULLTEXT} instead. Will be removed in 2.0.
      */
     public const INDEX_FULLTEXT = 'FULLTEXT';
     /**
      * Define the type of the index as `SPATIAL`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MySQL`.
+     *
+     * @deprecated Use {@see IndexType::SPATIAL} instead. Will be removed in 2.0.
      */
     public const INDEX_SPATIAL = 'SPATIAL';
     /**
      * Define the type of the index as `GIST`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `PostgreSQL`.
+     *
+     * @deprecated Use {@see IndexMethod::GIST} instead. Will be removed in 2.0.
      */
     public const INDEX_GIST = 'GIST';
     /**
      * Define the type of the index as `GIN`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `PostgreSQL`.
+     *
+     * @deprecated Use {@see IndexMethod::GIN} instead. Will be removed in 2.0.
      */
     public const INDEX_GIN = 'GIN';
     /**
      * Define the type of the index as `BRIN`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `PostgreSQL`.
+     *
+     * @deprecated Use {@see IndexMethod::BRIN} instead. Will be removed in 2.0.
      */
     public const INDEX_BRIN = 'BRIN';
     /**
      * Define the type of the index as `CLUSTERED`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MSSQL`.
+     *
+     * @deprecated Use {@see IndexType::CLUSTERED} instead. Will be removed in 2.0.
      */
     public const INDEX_CLUSTERED = 'CLUSTERED';
     /**
      * Define the type of the index as `NONCLUSTERED`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `MSSQL`.
+     *
+     * @deprecated Use {@see IndexType::NONCLUSTERED} instead. Will be removed in 2.0.
      */
     public const INDEX_NONCLUSTERED = 'NONCLUSTERED';
     /**
      * Define the type of the index as `BITMAP`, it's used in {@see DDLQueryBuilderInterface::createIndex()}.
      *
      * Supported by `Oracle`.
+     *
+     * @deprecated Use {@see IndexType::BITMAP} instead. Will be removed in 2.0.
      */
     public const INDEX_BITMAP = 'BITMAP';
     /**
diff --git a/tests/Common/CommonCommandTest.php b/tests/Common/CommonCommandTest.php
index b43ac3334..2196a8a72 100644
--- a/tests/Common/CommonCommandTest.php
+++ b/tests/Common/CommonCommandTest.php
@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Db\Tests\Common;
 
+use PHPUnit\Framework\Attributes\DataProviderExternal;
 use ReflectionException;
 use Throwable;
 use Yiisoft\Db\Constant\DataType;
@@ -28,11 +29,14 @@
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
 use Yiisoft\Db\Schema\Column\ColumnBuilder;
 use Yiisoft\Db\Tests\AbstractCommandTest;
+use Yiisoft\Db\Tests\Provider\CommandProvider;
 use Yiisoft\Db\Tests\Support\Assert;
 use Yiisoft\Db\Transaction\TransactionInterface;
 
+use function array_filter;
 use function is_string;
 use function setlocale;
+use function str_starts_with;
 
 abstract class CommonCommandTest extends AbstractCommandTest
 {
@@ -486,45 +490,36 @@ static function () {
         $db->close();
     }
 
-    /**
-     * @dataProvider \Yiisoft\Db\Tests\Provider\CommandProvider::createIndex
-     *
-     * @throws Exception
-     * @throws InvalidConfigException
-     * @throws Throwable
-     */
-    public function testCreateIndex(
-        string $name,
-        string $tableName,
-        array|string $column,
-        string|null $indexType,
-        string|null $indexMethod,
-    ): void {
+    #[DataProviderExternal(CommandProvider::class, 'createIndex')]
+    public function testCreateIndex(array $columns, array $indexColumns, string|null $indexType, string|null $indexMethod): void
+    {
         $db = $this->getConnection();
 
         $command = $db->createCommand();
         $schema = $db->getSchema();
 
+        $tableName = 'test_create_index';
+        $indexName = 'test_index_name';
+
         if ($schema->getTableSchema($tableName) !== null) {
             $command->dropTable($tableName)->execute();
         }
 
-        $command->createTable($tableName, ['int1' => 'integer not null', 'int2' => 'integer not null'])->execute();
+        $command->createTable($tableName, $columns)->execute();
 
-        $this->assertEmpty($schema->getTableIndexes($tableName, true));
+        $count = count($schema->getTableIndexes($tableName));
+        $command->createIndex($tableName, $indexName, $indexColumns, $indexType, $indexMethod)->execute();
 
-        $command->createIndex($tableName, $name, $column, $indexType, $indexMethod)->execute();
+        $this->assertCount($count + 1, $schema->getTableIndexes($tableName));
 
-        if (is_string($column)) {
-            $column = [$column];
-        }
+        $index = array_filter($schema->getTableIndexes($tableName), static fn ($index) => !$index->isPrimary())[0];
 
-        $this->assertSame($column, $schema->getTableIndexes($tableName, true)[0]->getColumnNames());
+        $this->assertSame($indexColumns, $index->getColumnNames());
 
-        if ($indexType === 'UNIQUE') {
-            $this->assertTrue($schema->getTableIndexes($tableName, true)[0]->isUnique());
+        if ($indexType !== null && str_starts_with($indexType, 'UNIQUE')) {
+            $this->assertTrue($index->isUnique());
         } else {
-            $this->assertFalse($schema->getTableIndexes($tableName, true)[0]->isUnique());
+            $this->assertFalse($index->isUnique());
         }
 
         $db->close();
diff --git a/tests/Common/CommonSchemaTest.php b/tests/Common/CommonSchemaTest.php
index ac58fed79..a6984b1c1 100644
--- a/tests/Common/CommonSchemaTest.php
+++ b/tests/Common/CommonSchemaTest.php
@@ -9,6 +9,7 @@
 use Throwable;
 use Yiisoft\Db\Connection\ConnectionInterface;
 use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Constraint\CheckConstraint;
 use Yiisoft\Db\Constraint\Constraint;
 use Yiisoft\Db\Constraint\DefaultValueConstraint;
@@ -18,7 +19,6 @@
 use Yiisoft\Db\Exception\InvalidCallException;
 use Yiisoft\Db\Exception\InvalidConfigException;
 use Yiisoft\Db\Exception\NotSupportedException;
-use Yiisoft\Db\Schema\SchemaInterface;
 use Yiisoft\Db\Schema\TableSchemaInterface;
 use Yiisoft\Db\Tests\AbstractSchemaTest;
 use Yiisoft\Db\Tests\Support\AnyCaseValue;
@@ -147,7 +147,7 @@ public function testFindUniquesIndexes(): void
             'uniqueIndex',
             'somecolUnique',
             'somecol',
-            SchemaInterface::INDEX_UNIQUE,
+            IndexType::UNIQUE,
         )->execute();
         $tableSchema = $schema->getTableSchema('uniqueIndex', true);
 
@@ -166,7 +166,7 @@ public function testFindUniquesIndexes(): void
             'uniqueIndex',
             'someCol2Unique',
             'someCol2',
-            SchemaInterface::INDEX_UNIQUE,
+            IndexType::UNIQUE,
         )->execute();
         $tableSchema = $schema->getTableSchema('uniqueIndex', true);
 
@@ -181,7 +181,7 @@ public function testFindUniquesIndexes(): void
             'uniqueIndex',
             'another unique index',
             'someCol3',
-            SchemaInterface::INDEX_UNIQUE,
+            IndexType::UNIQUE,
         )->execute();
         $tableSchema = $schema->getTableSchema('uniqueIndex', true);
 
diff --git a/tests/Provider/CommandProvider.php b/tests/Provider/CommandProvider.php
index d0387d58f..7f559e01f 100644
--- a/tests/Provider/CommandProvider.php
+++ b/tests/Provider/CommandProvider.php
@@ -10,10 +10,10 @@
 use Yiisoft\Db\Constant\DataType;
 use Yiisoft\Db\Command\Param;
 use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Expression\Expression;
 use Yiisoft\Db\Query\Query;
 use Yiisoft\Db\Schema\Column\ColumnBuilder;
-use Yiisoft\Db\Schema\SchemaInterface;
 use Yiisoft\Db\Tests\Support\DbHelper;
 use Yiisoft\Db\Tests\Support\Stringable;
 use Yiisoft\Db\Tests\Support\TestTrait;
@@ -511,9 +511,9 @@ public function getIterator(): Traversable
     public static function createIndex(): array
     {
         return [
-            ['{{test_idx_constraint_1}}', '{{test_idx}}', 'int1', null, null],
-            ['{{test_idx_constraint_2}}', '{{test_idx}}', ['int1'], SchemaInterface::INDEX_UNIQUE, null],
-            ['{{test_idx_constraint_3}}', '{{test_idx}}', ['int1', 'int2'], null, null],
+            [['col1' => ColumnBuilder::integer()], ['col1'], null, null],
+            [['col1' => ColumnBuilder::integer()], ['col1'], IndexType::UNIQUE, null],
+            [['col1' => ColumnBuilder::integer(), 'col2' => ColumnBuilder::integer()], ['col1', 'col2'], null, null],
         ];
     }
 
@@ -550,7 +550,7 @@ public static function createIndexSql(): array
                 '{{name}}',
                 '{{table}}',
                 ['column1', 'column2'],
-                SchemaInterface::INDEX_UNIQUE,
+                IndexType::UNIQUE,
                 '',
                 DbHelper::replaceQuotes(
                     <<<SQL
diff --git a/tests/Provider/QueryBuilderProvider.php b/tests/Provider/QueryBuilderProvider.php
index 977a0bf39..45ffd38b8 100644
--- a/tests/Provider/QueryBuilderProvider.php
+++ b/tests/Provider/QueryBuilderProvider.php
@@ -8,6 +8,7 @@
 use Yiisoft\Db\Constant\DataType;
 use Yiisoft\Db\Command\Param;
 use Yiisoft\Db\Constant\ColumnType;
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Constant\PseudoType;
 use Yiisoft\Db\Constraint\ForeignKeyConstraint;
 use Yiisoft\Db\Expression\Expression;
@@ -18,7 +19,6 @@
 use Yiisoft\Db\QueryBuilder\Condition\LikeCondition;
 use Yiisoft\Db\QueryBuilder\QueryBuilderInterface;
 use Yiisoft\Db\Schema\Column\ColumnBuilder;
-use Yiisoft\Db\Schema\SchemaInterface;
 use Yiisoft\Db\Tests\Support\DbHelper;
 use Yiisoft\Db\Tests\Support\Stringable;
 use Yiisoft\Db\Tests\Support\TestTrait;
@@ -936,7 +936,7 @@ public static function createIndex(): array
                     $tableName,
                     $name1,
                     'C_index_1',
-                    SchemaInterface::INDEX_UNIQUE,
+                    IndexType::UNIQUE,
                 ),
             ],
             'create unique (2 columns)' => [
@@ -947,7 +947,7 @@ public static function createIndex(): array
                     $tableName,
                     $name2,
                     'C_index_2_1, C_index_2_2',
-                    SchemaInterface::INDEX_UNIQUE,
+                    IndexType::UNIQUE,
                 ),
             ],
         ];
diff --git a/tests/Provider/SchemaProvider.php b/tests/Provider/SchemaProvider.php
index bd451a4d1..fe840547d 100644
--- a/tests/Provider/SchemaProvider.php
+++ b/tests/Provider/SchemaProvider.php
@@ -5,6 +5,7 @@
 namespace Yiisoft\Db\Tests\Provider;
 
 use PDO;
+use Yiisoft\Db\Constant\IndexType;
 use Yiisoft\Db\Constraint\CheckConstraint;
 use Yiisoft\Db\Constraint\Constraint;
 use Yiisoft\Db\Constraint\ForeignKeyConstraint;
@@ -190,7 +191,7 @@ public static function withIndexDataProvider(): array
     {
         return [
             [
-                'indexType' => SchemaInterface::INDEX_UNIQUE,
+                'indexType' => IndexType::UNIQUE,
                 'indexMethod' => null,
                 'columnType' => null,
                 'isPrimary' => false,