Deprecate Index features and introduce IndexEditor

UPGRADE.md

@@ -8,6 +8,34 @@ awareness about deprecated code.
 
 # Upgrade to 4.3
 
+## Deprecated `Index` methods, properties and behavior
+
+The following `Index` methods and properties have been deprecated:
+
+- `Index::getColumns()`, `Index::getQuotedColumns()`, `Index::getUnquotedColumns()`,
+  `Index::$_columns` – use `Index::getIndexedColumns()` instead.
+- `Index::isSimpleIndex()`, `Index::isUnique()`, `Index::$_isUnique` – use `Index::getType()` and compare with
+  `IndexType::REGULAR` or `IndexType::UNIQUE` instead.
+- `Index::addFlag()`, `Index::removeFlag()`, `Index::getFlags()`, `Index::hasFlag()`, `Index::$_flags` – use
+  `IndexEditor::setType()`, `Index::getType()`, `IndexEditor::setIsClustered()` and `Index::isClustered()` instead.
+- `Index::getOption()`, `Index::hasOption()` and `Index::getOptions()` – use `Index::getIndexedColumns()` and
+  `Index::getPredicate()` instead.
+- `Index::overrules()`, `Index::hasColumnAtPosition()` – no replacement provided.
+- `AbstractPlatform::supportsColumnLengthIndexes()` – no replacement provided.
+
+Additionally,
+1. Instantiation of an index without columns is deprecated.
+2. The `Index::spansColumns()` method has been marked as internal.
+3. Passing an empty string as partial index predicate has been deprecated.
+4. The `Index` constructor has been marked as internal. Use `Index::editor()` to instantiate an editor and
+   `IndexEditor::create()` to create an index.
+
+The following conflicting index configurations have been deprecated:
+1. Spatial index with column lengths specified.
+2. Clustered fulltext or spatial index.
+3. Partial fulltext or spatial index.
+4. Clustered partial index.
+
 ## Deprecated features related to primary key constraints
 
 1. The `AbstractPlatform::getCreatePrimaryKeySQL()` method has been deprecated. Use the schema manager to create and
@@ -129,7 +157,7 @@ the `Schema` class itself.
 
 ## Deprecated `ForeignKeyConstraint` methods, properties and behavior
 
-The following `ForeignKeyConstraint` methods and property have been deprecated:
+The following `ForeignKeyConstraint` methods and properties have been deprecated:
 
 - `ForeignKeyConstraint::getForeignTableName()`, `ForeignKeyConstraint::getQuotedForeignTableName()`,
   `ForeignKeyConstraint::getUnqualifiedForeignTableName()`, `ForeignKeyConstraint::$_foreignTableName` – use

src/Platforms/AbstractMySQLPlatform.php

@@ -846,8 +846,16 @@ public function getDefaultTransactionIsolationLevel(): TransactionIsolationLevel
         return TransactionIsolationLevel::REPEATABLE_READ;
     }
 
+    /** @deprecated */
     public function supportsColumnLengthIndexes(): bool
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6886',
+            '%s is deprecated.',
+            __METHOD__,
+        );
+
         return true;
     }
 

src/Platforms/AbstractPlatform.php

@@ -2053,9 +2053,18 @@ public function supportsPartialIndexes(): bool
 
     /**
      * Whether the platform supports indexes with column length definitions.
+     *
+     * @deprecated
      */
     public function supportsColumnLengthIndexes(): bool
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6886',
+            '%s is deprecated.',
+            __METHOD__,
+        );
+
         return false;
     }
 

src/Schema/Exception/InvalidIndexDefinition.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Schema\Exception;
+
+use Doctrine\DBAL\Schema\SchemaException;
+use LogicException;
+
+use function sprintf;
+
+final class InvalidIndexDefinition extends LogicException implements SchemaException
+{
+    public static function nameNotSet(): self
+    {
+        return new self('Index name is not set.');
+    }
+
+    public static function columnsNotSet(): self
+    {
+        return new self('Index column names are not set.');
+    }
+
+    public static function fromNonPositiveColumnLength(int $length): self
+    {
+        return new self(sprintf('Indexed column length must be a positive integer, %d given.', $length));
+    }
+}

src/Schema/Exception/InvalidState.php

@@ -16,6 +16,16 @@ public static function objectNameNotInitialized(): self
         return new self('Object name has not been initialized.');
     }
 
+    public static function indexHasInvalidType(string $indexName): self
+    {
+        return new self(sprintf('Index "%s" has invalid type.', $indexName));
+    }
+
+    public static function indexHasInvalidPredicate(string $indexName): self
+    {
+        return new self(sprintf('Index "%s" has invalid predicate.', $indexName));
+    }
+
     public static function indexHasInvalidColumns(string $indexName): self
     {
         return new self(sprintf('Index "%s" has invalid columns.', $indexName));