Deprecate invalid method call

`getAssociationMappedByTargetField()` returns `null` when called with
the owning side of an association.
This is undocumented and wrong because the phpdoc advertises a string as
a return type.

Instead, callers should ensure they are calling that method with an
inverse side.

Closes #11250

UPGRADE.md

@@ -1,5 +1,16 @@
 # Upgrade to 2.19
 
+## Deprecate calling `ClassMetadata::getAssociationMappedByTargetField()` with the owning side of an association
+
+Calling
+`Doctrine\ORM\Mapping\ClassMetadata::getAssociationMappedByTargetField()` with
+the owning side of an association returns `null`, which is undocumented, and
+wrong according to the phpdoc of the parent method.
+
+If you do not know whether you are on the owning or inverse side of an association,
+you can use  `Doctrine\ORM\Mapping\ClassMetadata::isAssociationInverseSide()`
+to find out.
+
 ## Deprecate `Doctrine\ORM\Query\Lexer::T_*` constants
 
 Use `Doctrine\ORM\Query\TokenType::T_*` instead.

src/Mapping/ClassMetadataInfo.php

@@ -3681,6 +3681,17 @@ public function isAssociationInverseSide($fieldName)
      */
     public function getAssociationMappedByTargetField($fieldName)
     {
+        if (! $this->isAssociationInverseSide($fieldName)) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/11309',
+                'Calling %s with owning side field %s is deprecated and will no longer be supported in Doctrine ORM 3.0. Call %s::isAssociationInverseSide() to check first.',
+                __METHOD__,
+                $fieldName,
+                self::class
+            );
+        }
+
         return $this->associationMappings[$fieldName]['mappedBy'];
     }
 

tests/Tests/ORM/Mapping/ClassMetadataTest.php

@@ -6,6 +6,7 @@
 
 use ArrayObject;
 use Doctrine\DBAL\Types\Types;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\ORM\Events;
 use Doctrine\ORM\Mapping\ChainTypedFieldMapper;
 use Doctrine\ORM\Mapping\ClassMetadata;
@@ -54,6 +55,8 @@
 
 class ClassMetadataTest extends OrmTestCase
 {
+    use VerifyDeprecations;
+
     public function testClassMetadataInstanceSerialization(): void
     {
         $cm = new ClassMetadata(CMS\CmsUser::class);
@@ -1379,6 +1382,16 @@ public function testRejectsEmbeddableWithoutValidClassName(): void
             'columnPrefix' => false,
         ]);
     }
+
+    public function testInvalidCallToGetAssociationMappedByTargetFieldIsDeprecated(): void
+    {
+        $metadata = new ClassMetadata(self::class);
+        $metadata->mapOneToOne(['fieldName' => 'foo', 'targetEntity' => 'bar']);
+
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/pull/11309');
+
+        $metadata->getAssociationMappedByTargetField('foo');
+    }
 }
 
 /** @MappedSuperclass */