Translate comment into code and annotations

UPGRADE.md

@@ -1,5 +1,10 @@
 # Upgrade to 3.1
 
+## Deprecate passing null to `ClassMetadata::fullyQualifiedClassName()`
+
+Passing `null` to `Doctrine\ORM\ClassMetadata::fullyQualifiedClassName()` is
+deprecated and will no longer be possible in 4.0.
+
 ## Deprecate array access
 
 Using array access on instances of the following classes is deprecated:

psalm-baseline.xml

@@ -290,11 +290,6 @@
       <code>$repositoryClassName</code>
     </ArgumentTypeCoercion>
   </file>
-  <file src="src/Mapping/Builder/EntityListenerBuilder.php">
-    <PossiblyNullArgument>
-      <code>$class</code>
-    </PossiblyNullArgument>
-  </file>
   <file src="src/Mapping/ClassMetadata.php">
     <DeprecatedProperty>
       <code><![CDATA[$this->columnNames]]></code>
@@ -322,8 +317,6 @@
       <code>$entity</code>
     </ParamNameMismatch>
     <PossiblyNullArgument>
-      <code>$class</code>
-      <code>$className</code>
       <code><![CDATA[$mapping['targetEntity']]]></code>
       <code><![CDATA[$mapping['targetEntity']]]></code>
       <code><![CDATA[$parentReflFields[$embeddedClass->declaredField]]]></code>

src/Mapping/ClassMetadata.php

@@ -7,6 +7,7 @@
 use BackedEnum;
 use BadMethodCallException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\Instantiator\Instantiator;
 use Doctrine\Instantiator\InstantiatorInterface;
 use Doctrine\ORM\Cache\Exception\NonCacheableEntityAssociation;
@@ -2003,6 +2004,12 @@ protected function _storeAssociationMapping(AssociationMapping $assocMapping): v
      */
     public function setCustomRepositoryClass(string|null $repositoryClassName): void
     {
+        if ($repositoryClassName === null) {
+            $this->customRepositoryClassName = null;
+
+            return;
+        }
+
         $this->customRepositoryClassName = $this->fullyQualifiedClassName($repositoryClassName);
     }
 
@@ -2464,11 +2471,25 @@ public function getAssociationMappedByTargetField(string $assocName): string
         return $assoc->mappedBy;
     }
 
-    /** @return string|null null if the input value is null */
+    /**
+     * @param C $className
+     *
+     * @return string|null null if and only if the input value is null
+     * @psalm-return (C is class-string ? class-string : (C is string ? string : null))
+     *
+     * @template C of string|null
+     */
     public function fullyQualifiedClassName(string|null $className): string|null
     {
-        if (empty($className)) {
-            return $className;
+        if ($className === null) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/11294',
+                'Passing null to %s is deprecated and will not be supported in Doctrine ORM 4.0',
+                __METHOD__,
+            );
+
+            return null;
         }
 
         if (! str_contains($className, '\\') && $this->namespace) {
@@ -2511,12 +2532,8 @@ public function mapEmbedded(array $mapping): void
             throw MappingException::missingEmbeddedClass($mapping['fieldName']);
         }
 
-        $fqcn = $this->fullyQualifiedClassName($mapping['class']);
-
-        assert($fqcn !== null);
-
         $this->embeddedClasses[$mapping['fieldName']] = EmbeddedClassMapping::fromMappingArray([
-            'class' => $fqcn,
+            'class' => $this->fullyQualifiedClassName($mapping['class']),
             'columnPrefix' => $mapping['columnPrefix'] ?? null,
             'declaredField' => $mapping['declaredField'] ?? null,
             'originalField' => $mapping['originalField'] ?? null,

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;
@@ -66,6 +67,8 @@
 
 class ClassMetadataTest extends OrmTestCase
 {
+    use VerifyDeprecations;
+
     public function testClassMetadataInstanceSerialization(): void
     {
         $cm = new ClassMetadata(CmsUser::class);
@@ -1052,6 +1055,15 @@ public function testItAddingLifecycleCallbackOnEmbeddedClassIsIllegal(): void
 
         $metadata->addLifecycleCallback('foo', 'bar');
     }
+
+    public function testGettingAnFQCNForNullIsDeprecated(): void
+    {
+        $metadata = new ClassMetadata(self::class);
+
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/pull/11294');
+
+        $metadata->fullyQualifiedClassName(null);
+    }
 }
 
 #[MappedSuperclass]