Deprecate and mark internal APIs related to schema comparison

UPGRADE.md

@@ -13,10 +13,20 @@ awareness about deprecated code.
 Relying on the default precision and scale of decimal columns provided by the DBAL is deprecated.
 When declaring decimal columns, specify the precision and scale explicitly.
 
-## Marked `ColumnDiff::hasChanged()` as internal.
+## Marked `Comparator` methods as internal.
 
-The `ColumnDiff::hasChanged()` method has been marked as internal. Use one of the following `ColumnDiff` methods
-in order to check if a given column property has changed:
+The following `Comparator` methods have been marked as internal:
+
+- `columnsEqual()`,
+- `diffForeignKey()`,
+- `diffIndex()`.
+
+The `diffColumn()` method has been deprecated. Use `diffTable()` instead.
+
+## Deprecated `ColumnDiff::$changedProperties` and `::hasChanged()`.
+
+The `ColumnDiff::$changedProperties` property and the `hasChanged()` method have been deprecated. Use one of the
+following `ColumnDiff` methods in order to check if a given column property has changed:
 
 - `hasTypeChanged()`,
 - `hasLengthChanged()`,

psalm.xml.dist

@@ -418,6 +418,11 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedMethod name="Doctrine\DBAL\Schema\ColumnDiff::getOldColumnName"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Schema\ColumnDiff::hasChanged"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\Comparator::diffColumn"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>
@@ -451,6 +456,10 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedProperty name="Doctrine\DBAL\Schema\ColumnDiff::$oldColumnName"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedProperty name="Doctrine\DBAL\Schema\ColumnDiff::$changedProperties"/>
             </errorLevel>
         </DeprecatedProperty>
         <DocblockTypeContradiction>

src/Schema/ColumnDiff.php

@@ -21,7 +21,13 @@ class ColumnDiff
     /** @var Column */
     public $column;
 
-    /** @var string[] */
+    /**
+     * @deprecated Use {@see hasTypeChanged()}, {@see hasLengthChanged()}, {@see hasPrecisionChanged()},
+     * {@see hasScaleChanged()}, {@see hasUnsignedChanged()}, {@see hasFixedChanged()}, {@see hasNotNullChanged()},
+     * {@see hasDefaultChanged()}, {@see hasAutoIncrementChanged()} or {@see hasCommentChanged()} instead.
+     *
+     * @var string[]
+     */
     public $changedProperties = [];
 
     /** @var Column|null */
@@ -105,7 +111,9 @@ public function hasCommentChanged(): bool
     }
 
     /**
-     * @internal
+     * @deprecated Use {@see hasTypeChanged()}, {@see hasLengthChanged()}, {@see hasPrecisionChanged()},
+     * {@see hasScaleChanged()}, {@see hasUnsignedChanged()}, {@see hasFixedChanged()}, {@see hasNotNullChanged()},
+     * {@see hasDefaultChanged()}, {@see hasAutoIncrementChanged()} or {@see hasCommentChanged()} instead.
      *
      * @param string $propertyName
      *

src/Schema/Comparator.php

@@ -467,7 +467,11 @@ private function detectIndexRenamings(TableDiff $tableDifferences): void
         }
     }
 
-    /** @return bool */
+    /**
+     * @internal The method should be only used from within the {@see Comparator} class hierarchy.
+     *
+     * @return bool
+     */
     public function diffForeignKey(ForeignKeyConstraint $key1, ForeignKeyConstraint $key2)
     {
         if (
@@ -498,6 +502,8 @@ public function diffForeignKey(ForeignKeyConstraint $key1, ForeignKeyConstraint
     /**
      * Compares the definitions of the given columns
      *
+     * @internal The method should be only used from within the {@see Comparator} class hierarchy.
+     *
      * @throws Exception
      */
     public function columnsEqual(Column $column1, Column $column2): bool
@@ -515,10 +521,19 @@ public function columnsEqual(Column $column1, Column $column2): bool
      * If there are differences this method returns the changed properties as a
      * string array, otherwise an empty array gets returned.
      *
+     * @deprecated Use {@see diffTable()} instead.
+     *
      * @return string[]
      */
     public function diffColumn(Column $column1, Column $column2)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5650',
+            '%s is deprecated. Use diffTable() instead.',
+            __METHOD__,
+        );
+
         $properties1 = $column1->toArray();
         $properties2 = $column2->toArray();
 
@@ -609,6 +624,8 @@ public function diffColumn(Column $column1, Column $column2)
      * Compares $index1 with $index2 and returns $index2 if there are any
      * differences or false in case there are no differences.
      *
+     * @internal The method should be only used from within the {@see Comparator} class hierarchy.
+     *
      * @return bool
      */
     public function diffIndex(Index $index1, Index $index2)