Deprecate reference from foreign key to its referencing table

UPGRADE.md

@@ -8,6 +8,18 @@ awareness about deprecated code.
 
 # Upgrade to 3.2
 
+## Deprecated reference from `ForeignKeyConstraint` to its local (referencing) `Table`.
+
+Reference from `ForeignKeyConstraint` to its local (referencing) `Table` is deprecated as well as the following methods:
+
+- `setLocalTable()`,
+- `getLocalTable()`,
+- `getLocalTableName()`.
+
+When a foreign key is used as part of the `Table` definition, the table should be used directly. When a foreign key is
+used as part of another collection (e.g. `SchemaDiff`), the collection should store the reference to the key's
+referencing table separately.
+
 ## Deprecated redundant `AbstractPlatform` methods.
 
 The following methods implement simple SQL fragments that don't vary across supported platforms. The SQL fragments

psalm.xml.dist

@@ -118,6 +118,13 @@
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getUniqueFieldDeclarationSQL"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::supportsAlterTable"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::supportsViews"/>
+                <!--
+                    See https://github.com/doctrine/dbal/pull/4742
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Schema\ForeignKeyConstraint::getLocalTable"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\ForeignKeyConstraint::getLocalTableName"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\ForeignKeyConstraint::setLocalTable"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>

src/Schema/ForeignKeyConstraint.php

@@ -105,6 +105,8 @@ private function createIdentifierMap(array $names): array
      * Returns the name of the referencing table
      * the foreign key constraint is associated with.
      *
+     * @deprecated Use the table that contains the foreign key as part of its {@link Table::$_fkConstraints} instead.
+     *
      * @return string
      */
     public function getLocalTableName()
@@ -116,6 +118,8 @@ public function getLocalTableName()
      * Sets the Table instance of the referencing table
      * the foreign key constraint is associated with.
      *
+     * @deprecated Use the table that contains the foreign key as part of its {@link Table::$_fkConstraints} instead.
+     *
      * @param Table $table Instance of the referencing table.
      *
      * @return void
@@ -126,6 +130,8 @@ public function setLocalTable(Table $table)
     }
 
     /**
+     * @deprecated Use the table that contains the foreign key as part of its {@link Table::$_fkConstraints} instead.
+     *
      * @return Table
      */
     public function getLocalTable()