Merge branch '2.20.x' into 3.3.x

* 2.20.x: Remove vendor prefix of PHPDoc referencing class-string (doctrine#11643) Deprecate the `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()` method (doctrine#11641)
derrabus · Oct 9, 2024 · 5f39343 · 5f39343
2 parents 3079555 + 488a5dd
commit 5f39343
Show file tree

Hide file tree

Showing 32 changed files with 126 additions and 128 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -746,6 +746,12 @@ Progress on this is tracked at https://github.com/doctrine/orm/issues/11624 .
 Use of the PARTIAL keyword is not deprecated anymore in DQL when used with a hydrator
 that is not creating entities, such as the ArrayHydrator.
 
+## Deprecate `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()`
+
+Use the `\Doctrine\ORM\Query::HINT_CUSTOM_OUTPUT_WALKER` query hint to set the output walker
+class instead of setting it through the `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()` method
+on the parser instance.
+
 # Upgrade to 2.19
 
 ## Deprecate calling `ClassMetadata::getAssociationMappedByTargetField()` with the owning side of an association

diff --git a/src/Cache/CollectionCacheKey.php b/src/Cache/CollectionCacheKey.php
@@ -22,8 +22,8 @@ class CollectionCacheKey extends CacheKey
     public readonly array $ownerIdentifier;
 
     /**
+     * @param class-string         $entityClass     The owner entity class.
      * @param array<string, mixed> $ownerIdentifier The identifier of the owning entity.
-     * @param class-string         $entityClass     The owner entity class
      */
     public function __construct(
         public readonly string $entityClass,

diff --git a/src/Cache/EntityCacheEntry.php b/src/Cache/EntityCacheEntry.php
@@ -11,8 +11,8 @@
 class EntityCacheEntry implements CacheEntry
 {
     /**
-     * @param array<string,mixed> $data The entity map data
-     * @psalm-param class-string $class The entity class name
+     * @param class-string        $class The entity class name
+     * @param array<string,mixed> $data  The entity map data
      */
     public function __construct(
         public readonly string $class,

diff --git a/src/Configuration.php b/src/Configuration.php
@@ -263,8 +263,8 @@ public function getCustomNumericFunction(string $name): string|callable|null
      *
      * Any previously added numeric functions are discarded.
      *
-     * @psalm-param array<string, class-string> $functions The map of custom
-     *                                                     DQL numeric functions.
+     * @param array<string, class-string> $functions The map of custom
+     *                                               DQL numeric functions.
      */
     public function setCustomNumericFunctions(array $functions): void
     {
@@ -291,7 +291,7 @@ public function addCustomDatetimeFunction(string $name, string|callable $classNa
     /**
      * Gets the implementation class name of a registered custom date/time DQL function.
      *
-     * @psalm-return class-string|callable|null
+     * @return class-string|callable|null
      */
     public function getCustomDatetimeFunction(string $name): string|callable|null
     {
@@ -351,7 +351,7 @@ public function setCustomHydrationModes(array $modes): void
     /**
      * Gets the hydrator class for the given hydration mode name.
      *
-     * @psalm-return class-string<AbstractHydrator>|null
+     * @return class-string<AbstractHydrator>|null
      */
     public function getCustomHydrationMode(string $modeName): string|null
     {
@@ -361,7 +361,7 @@ public function getCustomHydrationMode(string $modeName): string|null
     /**
      * Adds a custom hydration mode.
      *
-     * @psalm-param class-string<AbstractHydrator> $hydrator
+     * @param class-string<AbstractHydrator> $hydrator
      */
     public function addCustomHydrationMode(string $modeName, string $hydrator): void
     {
@@ -371,14 +371,14 @@ public function addCustomHydrationMode(string $modeName, string $hydrator): void
     /**
      * Sets a class metadata factory.
      *
-     * @psalm-param class-string $cmfName
+     * @param class-string $cmfName
      */
     public function setClassMetadataFactoryName(string $cmfName): void
     {
         $this->attributes['classMetadataFactoryName'] = $cmfName;
     }
 
-    /** @psalm-return class-string */
+    /** @return class-string */
     public function getClassMetadataFactoryName(): string
     {
         if (! isset($this->attributes['classMetadataFactoryName'])) {
@@ -391,8 +391,7 @@ public function getClassMetadataFactoryName(): string
     /**
      * Adds a filter to the list of possible filters.
      *
-     * @param string $className The class name of the filter.
-     * @psalm-param class-string<SQLFilter> $className
+     * @param class-string<SQLFilter> $className The class name of the filter.
      */
     public function addFilter(string $name, string $className): void
     {
@@ -402,9 +401,8 @@ public function addFilter(string $name, string $className): void
     /**
      * Gets the class name for a given filter name.
      *
-     * @return string|null The class name of the filter, or null if it is not
-     *  defined.
-     * @psalm-return class-string<SQLFilter>|null
+     * @return class-string<SQLFilter>|null The class name of the filter,
+     *                                      or null if it is not defined.
      */
     public function getFilterClassName(string $name): string|null
     {
@@ -414,7 +412,7 @@ public function getFilterClassName(string $name): string|null
     /**
      * Sets default repository class.
      *
-     * @psalm-param class-string<EntityRepository> $className
+     * @param class-string<EntityRepository> $className
      *
      * @throws InvalidEntityRepository If $classname is not an ObjectRepository.
      */
@@ -430,7 +428,7 @@ public function setDefaultRepositoryClassName(string $className): void
     /**
      * Get default repository class.
      *
-     * @psalm-return class-string<EntityRepository>
+     * @return class-string<EntityRepository>
      */
     public function getDefaultRepositoryClassName(): string
     {

diff --git a/src/EntityManager.php b/src/EntityManager.php
@@ -479,9 +479,9 @@ public function lock(object $entity, LockMode|int $lockMode, DateTimeInterface|i
     /**
      * Gets the repository for an entity class.
      *
-     * @psalm-param class-string<T> $className
+     * @param class-string<T> $className The name of the entity.
      *
-     * @psalm-return EntityRepository<T>
+     * @return EntityRepository<T> The repository class.
      *
      * @template T of object
      */

diff --git a/src/EntityManagerInterface.php b/src/EntityManagerInterface.php
@@ -22,9 +22,9 @@ interface EntityManagerInterface extends ObjectManager
     /**
      * {@inheritDoc}
      *
-     * @psalm-param class-string<T> $className
+     * @param class-string<T> $className
      *
-     * @psalm-return EntityRepository<T>
+     * @return EntityRepository<T>
      *
      * @template T of object
      */
@@ -151,11 +151,10 @@ public function refresh(object $object, LockMode|int|null $lockMode = null): voi
      * Gets a reference to the entity identified by the given type and identifier
      * without actually loading it, if the entity is not yet loaded.
      *
-     * @param string $entityName The name of the entity type.
-     * @param mixed  $id         The entity identifier.
-     * @psalm-param class-string<T> $entityName
+     * @param class-string<T> $entityName The name of the entity type.
+     * @param mixed           $id         The entity identifier.
      *
-     * @psalm-return T|null
+     * @return T|null The entity reference.
      *
      * @throws ORMException
      *
@@ -232,7 +231,7 @@ public function hasFilters(): bool;
     /**
      * {@inheritDoc}
      *
-     * @psalm-param string|class-string<T> $className
+     * @param string|class-string<T> $className
      *
      * @psalm-return ($className is class-string<T> ? Mapping\ClassMetadata<T> : Mapping\ClassMetadata<object>)
      *

diff --git a/src/EntityRepository.php b/src/EntityRepository.php
@@ -35,11 +35,11 @@
  */
 class EntityRepository implements ObjectRepository, Selectable
 {
-    /** @psalm-var class-string<T> */
+    /** @var class-string<T> */
     private readonly string $entityName;
     private static Inflector|null $inflector = null;
 
-    /** @psalm-param ClassMetadata<T> $class */
+    /** @param ClassMetadata<T> $class */
     public function __construct(
         private readonly EntityManagerInterface $em,
         private readonly ClassMetadata $class,
@@ -169,7 +169,7 @@ public function __call(string $method, array $arguments): mixed
         ));
     }
 
-    /** @psalm-return class-string<T> */
+    /** @return class-string<T> */
     protected function getEntityName(): string
     {
         return $this->entityName;

diff --git a/src/Internal/Hydration/ObjectHydrator.php b/src/Internal/Hydration/ObjectHydrator.php
@@ -265,7 +265,7 @@ private function getEntity(array $data, string $dqlAlias): object
     }
 
     /**
-     * @psalm-param class-string $className
+     * @param class-string $className
      * @psalm-param array<string, mixed> $data
      */
     private function getEntityFromIdentityMap(string $className, array $data): object|bool

diff --git a/src/Mapping/Builder/ClassMetadataBuilder.php b/src/Mapping/Builder/ClassMetadataBuilder.php
@@ -169,8 +169,8 @@ public function setSingleTableInheritance(): static
     /**
      * Sets the discriminator column details.
      *
-     * @psalm-param class-string<BackedEnum>|null $enumType
-     * @psalm-param array<string, mixed> $options
+     * @param class-string<BackedEnum>|null $enumType
+     * @param array<string, mixed>          $options
      *
      * @return $this
      */

diff --git a/src/Mapping/ClassMetadataFactory.php b/src/Mapping/ClassMetadataFactory.php
@@ -399,7 +399,7 @@ private function peekIfIsMappedSuperclass(string $className): bool
     /**
      * Gets the lower-case short name of a class.
      *
-     * @psalm-param class-string $className
+     * @param class-string $className
      */
     private function getShortName(string $className): string
     {

diff --git a/src/Mapping/DefaultEntityListenerResolver.php b/src/Mapping/DefaultEntityListenerResolver.php
@@ -11,7 +11,7 @@
  */
 class DefaultEntityListenerResolver implements EntityListenerResolver
 {
-    /** @psalm-var array<class-string, object> Map to store entity listener instances. */
+    /** @var array<class-string, object> Map to store entity listener instances. */
     private array $instances = [];
 
     public function clear(string|null $className = null): void

diff --git a/src/Mapping/Driver/AttributeDriver.php b/src/Mapping/Driver/AttributeDriver.php
@@ -69,8 +69,8 @@ public function isTransient(string $className): bool
     /**
      * {@inheritDoc}
      *
-     * @psalm-param class-string<T> $className
-     * @psalm-param ClassMetadata<T> $metadata
+     * @param class-string<T>  $className
+     * @param ClassMetadata<T> $metadata
      *
      * @template T of object
      */

diff --git a/src/Mapping/Driver/DatabaseDriver.php b/src/Mapping/Driver/DatabaseDriver.php
@@ -153,8 +153,8 @@ public function setInflector(Inflector $inflector): void
     /**
      * {@inheritDoc}
      *
-     * @psalm-param class-string<T> $className
-     * @psalm-param ClassMetadata<T> $metadata
+     * @param class-string<T>  $className
+     * @param ClassMetadata<T> $metadata
      *
      * @template T of object
      */
@@ -493,7 +493,7 @@ private function getTablePrimaryKeys(Table $table): array
     /**
      * Returns the mapped class name for a table if it exists. Otherwise return "classified" version.
      *
-     * @psalm-return class-string
+     * @return class-string
      */
     private function getClassNameForTable(string $tableName): string
     {

diff --git a/src/Mapping/Driver/XmlDriver.php b/src/Mapping/Driver/XmlDriver.php
@@ -72,8 +72,8 @@ public function __construct(
     /**
      * {@inheritDoc}
      *
-     * @psalm-param class-string<T> $className
-     * @psalm-param ClassMetadata<T> $metadata
+     * @param class-string<T>  $className
+     * @param ClassMetadata<T> $metadata
      *
      * @template T of object
      */
@@ -891,19 +891,19 @@ protected function loadMappingFile($file)
 
         if (isset($xmlElement->entity)) {
             foreach ($xmlElement->entity as $entityElement) {
-                /** @psalm-var class-string $entityName */
+                /** @var class-string $entityName */
                 $entityName          = (string) $entityElement['name'];
                 $result[$entityName] = $entityElement;
             }
         } elseif (isset($xmlElement->{'mapped-superclass'})) {
             foreach ($xmlElement->{'mapped-superclass'} as $mappedSuperClass) {
-                /** @psalm-var class-string $className */
+                /** @var class-string $className */
                 $className          = (string) $mappedSuperClass['name'];
                 $result[$className] = $mappedSuperClass;
             }
         } elseif (isset($xmlElement->embeddable)) {
             foreach ($xmlElement->embeddable as $embeddableElement) {
-                /** @psalm-var class-string $embeddableName */
+                /** @var class-string $embeddableName */
                 $embeddableName          = (string) $embeddableElement['name'];
                 $result[$embeddableName] = $embeddableElement;
             }

diff --git a/src/Mapping/MappedSuperclass.php b/src/Mapping/MappedSuperclass.php
@@ -10,7 +10,7 @@
 #[Attribute(Attribute::TARGET_CLASS)]
 final class MappedSuperclass implements MappingAttribute
 {
-    /** @psalm-param class-string<EntityRepository>|null $repositoryClass */
+    /** @param class-string<EntityRepository>|null $repositoryClass */
     public function __construct(
         public readonly string|null $repositoryClass = null,
     ) {

diff --git a/src/Query/Parser.php b/src/Query/Parser.php
@@ -5,6 +5,7 @@
 namespace Doctrine\ORM\Query;
 
 use Doctrine\Common\Lexer\Token;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Internal\Hydration\HydrationException;
 use Doctrine\ORM\Mapping\AssociationMapping;
@@ -50,7 +51,7 @@ final class Parser
 {
     /**
      * @readonly Maps BUILT-IN string function names to AST class names.
-     * @psalm-var array<string, class-string<Functions\FunctionNode>>
+     * @var array<string, class-string<Functions\FunctionNode>>
      */
     private static array $stringFunctions = [
         'concat'    => Functions\ConcatFunction::class,
@@ -63,7 +64,7 @@ final class Parser
 
     /**
      * @readonly Maps BUILT-IN numeric function names to AST class names.
-     * @psalm-var array<string, class-string<Functions\FunctionNode>>
+     * @var array<string, class-string<Functions\FunctionNode>>
      */
     private static array $numericFunctions = [
         'length'    => Functions\LengthFunction::class,
@@ -86,7 +87,7 @@ final class Parser
 
     /**
      * @readonly Maps BUILT-IN datetime function names to AST class names.
-     * @psalm-var array<string, class-string<Functions\FunctionNode>>
+     * @var array<string, class-string<Functions\FunctionNode>>
      */
     private static array $datetimeFunctions = [
         'current_date'      => Functions\CurrentDateFunction::class,
@@ -146,7 +147,7 @@ final class Parser
     /**
      * Any additional custom tree walkers that modify the AST.
      *
-     * @psalm-var list<class-string<TreeWalker>>
+     * @var list<class-string<TreeWalker>>
      */
     private array $customTreeWalkers = [];
 
@@ -176,17 +177,24 @@ public function __construct(private readonly Query $query)
      * Sets a custom tree walker that produces output.
      * This tree walker will be run last over the AST, after any other walkers.
      *
-     * @psalm-param class-string<SqlWalker> $className
+     * @param class-string<SqlWalker> $className
      */
     public function setCustomOutputTreeWalker(string $className): void
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/11641',
+            '%s is deprecated, set the output walker class with the \Doctrine\ORM\Query::HINT_CUSTOM_OUTPUT_WALKER query hint instead',
+            __METHOD__,
+        );
+
         $this->customOutputWalker = $className;
     }
 
     /**
      * Adds a custom tree walker for modifying the AST.
      *
-     * @psalm-param class-string<TreeWalker> $className
+     * @param class-string<TreeWalker> $className
      */
     public function addCustomTreeWalker(string $className): void
     {