Add deprecation layer for TableDiff methods (#6482)

|      Q       |   A
|------------- | -----------
| Type         | feature
| Fixed issues | N/A

#### Summary

#6280 removed columns without explicitly deprecating them. This PR adds
the missing deprecation layer.

Co-authored-by: Tofandel <[email protected]>

Author: derrabus

UPGRADE.md

@@ -8,6 +8,11 @@ awareness about deprecated code.
 
 # Upgrade to 4.1
 
+## Deprecated `TableDiff` methods
+
+The `TableDiff` methods `getModifiedColumns()` and `getRenamedColumns()` have been merged into a single
+method `getChangedColumns()`. Use this method instead.
+
 ## Deprecated support for MariaDB 10.4 and MySQL 5.7
 
 * Upgrade to MariaDB 10.5 or later.

psalm.xml.dist

@@ -59,6 +59,8 @@
                     See https://github.com/doctrine/dbal/pull/6202
                     TODO: remove in 4.0.0
                 -->
+                <referencedMethod name="Doctrine\DBAL\Schema\TableDiff::getModifiedColumns" />
+                <referencedMethod name="Doctrine\DBAL\Schema\TableDiff::getRenamedColumns" />
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractMySQLPlatform::getColumnTypeSQLSnippets" />
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractMySQLPlatform::getDatabaseNameSQL" />
 

src/Schema/TableDiff.php

@@ -4,7 +4,10 @@
 
 namespace Doctrine\DBAL\Schema;
 
+use Doctrine\Deprecations\Deprecation;
+
 use function array_filter;
+use function array_values;
 use function count;
 
 /**
@@ -60,6 +63,52 @@ public function getChangedColumns(): array
         return $this->changedColumns;
     }
 
+    /**
+     * @deprecated Use {@see getChangedColumns()} instead.
+     *
+     * @return list<ColumnDiff>
+     */
+    public function getModifiedColumns(): array
+    {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6280',
+            '%s is deprecated, use `getChangedColumns()` instead.',
+            __METHOD__,
+        );
+
+        return array_values(array_filter(
+            $this->getChangedColumns(),
+            static fn (ColumnDiff $diff): bool => $diff->countChangedProperties() > ($diff->hasNameChanged() ? 1 : 0),
+        ));
+    }
+
+    /**
+     * @deprecated Use {@see getChangedColumns()} instead.
+     *
+     * @return array<string,Column>
+     */
+    public function getRenamedColumns(): array
+    {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/6280',
+            '%s is deprecated, you should use `getChangedColumns()` instead.',
+            __METHOD__,
+        );
+        $renamed = [];
+        foreach ($this->getChangedColumns() as $diff) {
+            if (! $diff->hasNameChanged()) {
+                continue;
+            }
+
+            $oldColumnName           = $diff->getOldColumn()->getName();
+            $renamed[$oldColumnName] = $diff->getNewColumn();
+        }
+
+        return $renamed;
+    }
+
     /** @return array<Column> */
     public function getDroppedColumns(): array
     {

tests/Functional/Platform/RenameColumnTest.php

@@ -39,6 +39,7 @@ public function testColumnPositionRetainedAfterImplicitRenaming(string $columnNa
         self::assertEqualsIgnoringCase($newColumnName, $columns[0]->getName());
         self::assertEqualsIgnoringCase('c2', $columns[1]->getName());
         self::assertCount(1, self::getRenamedColumns($diff));
+        self::assertCount(1, $diff->getRenamedColumns());
     }
 
     /** @return array<string,Column> */
@@ -79,6 +80,8 @@ public function testColumnPositionRetainedAfterExplicitRenaming(string $columnNa
         $columns = $table->getColumns();
 
         self::assertCount(1, $diff->getChangedColumns());
+        self::assertCount(1, $diff->getRenamedColumns());
+        self::assertCount(1, $diff->getModifiedColumns());
         self::assertCount(2, $columns);
         self::assertEqualsIgnoringCase($newColumnName, $columns[0]->getName());
         self::assertEqualsIgnoringCase('c2', $columns[1]->getName());

tests/Functional/Schema/ComparatorTest.php

@@ -74,7 +74,9 @@ public function testRenameColumnComparison(): void
 
         $compareResult  = $comparator->compareTables($onlineTable, $table);
         $renamedColumns = RenameColumnTest::getRenamedColumns($compareResult);
+        self::assertSame($renamedColumns, $compareResult->getRenamedColumns());
         self::assertCount(3, $compareResult->getChangedColumns());
+        self::assertCount(2, $compareResult->getModifiedColumns());
         self::assertCount(2, $renamedColumns);
         self::assertArrayHasKey('test2', $renamedColumns);