Merge pull request #10054 from greg0ire/sa-fixes

* 2.13.x-enum-arrayhydration:
  Fix ArrayHydration of enums

.doctrine-project.json

@@ -12,21 +12,27 @@
             "upcoming": true
         },
         {
-            "name": "2.13",
-            "branchName": "2.13.x",
-            "slug": "2.13",
+            "name": "2.14",
+            "branchName": "2.14.x",
+            "slug": "2.14",
             "upcoming": true
         },
         {
-            "name": "2.12",
-            "branchName": "2.12.x",
-            "slug": "2.12",
+            "name": "2.13",
+            "branchName": "2.13.x",
+            "slug": "2.13",
             "current": true,
             "aliases": [
                 "current",
                 "stable"
             ]
         },
+        {
+            "name": "2.12",
+            "branchName": "2.12.x",
+            "slug": "2.12",
+            "maintained": false
+        },
         {
             "name": "2.11",
             "branchName": "2.11.x",

.github/workflows/coding-standard.yml

@@ -10,6 +10,4 @@ on:
 
 jobs:
   coding-standards:
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@1.4.1"
-    with:
-      php-version: "8.1"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@2.0.0"

.github/workflows/continuous-integration.yml

@@ -14,7 +14,7 @@ env:
 jobs:
   phpunit-smoke-check:
     name: "PHPUnit with SQLite"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:
@@ -76,7 +76,7 @@ jobs:
 
   phpunit-postgres:
     name: "PHPUnit with PostgreSQL"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
@@ -142,7 +142,7 @@ jobs:
 
   phpunit-mariadb:
     name: "PHPUnit with MariaDB"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
@@ -218,7 +218,7 @@ jobs:
 
   phpunit-mysql:
     name: "PHPUnit with MySQL"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
@@ -301,7 +301,7 @@ jobs:
 
   phpunit-lower-php-versions:
     name: "PHPUnit with SQLite"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:
@@ -334,7 +334,7 @@ jobs:
 
   upload_coverage:
     name: "Upload coverage to Codecov"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs:
       - "phpunit-smoke-check"
       - "phpunit-postgres"

.github/workflows/phpbench.yml

@@ -15,7 +15,7 @@ env:
 jobs:
   phpbench:
     name: "PHPBench"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:

.github/workflows/release-on-milestone-closed.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   release:
-    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@1.4.1"
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@2.0.0"
     secrets:
       GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
       GIT_AUTHOR_NAME: ${{ secrets.GIT_AUTHOR_NAME }}

.github/workflows/static-analysis.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   static-analysis-phpstan:
     name: "Static Analysis with PHPStan"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       fail-fast: false
@@ -68,7 +68,7 @@ jobs:
 
   static-analysis-psalm:
     name: "Static Analysis with Psalm"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       fail-fast: false

README.md

@@ -1,7 +1,7 @@
-| [3.0.x][3.0] | [2.13.x][2.13] | [2.12.x][2.12] |
+| [3.0.x][3.0] | [2.14.x][2.14] | [2.13.x][2.13] |
 |:----------------:|:----------------:|:----------:|
-| [![Build status][3.0 image]][3.0] | [![Build status][2.13 image]][2.13] | [![Build status][2.12 image]][2.12] |
-| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.13 coverage image]][2.13 coverage] | [![Coverage Status][2.12 coverage image]][2.12 coverage]  |
+| [![Build status][3.0 image]][3.0] | [![Build status][2.14 image]][2.14] | [![Build status][2.13 image]][2.13] |
+| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.14 coverage image]][2.14 coverage] | [![Coverage Status][2.13 coverage image]][2.13 coverage]  |
 
 [<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
 
@@ -22,11 +22,11 @@ without requiring unnecessary code duplication.
   [3.0]: https://github.com/doctrine/orm/tree/3.0.x
   [3.0 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.0.x/graph/badge.svg
   [3.0 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.0.x
+  [2.14 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.14.x
+  [2.14]: https://github.com/doctrine/orm/tree/2.14.x
+  [2.14 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.14.x/graph/badge.svg
+  [2.14 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.14.x
   [2.13 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.13.x
   [2.13]: https://github.com/doctrine/orm/tree/2.13.x
   [2.13 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.13.x/graph/badge.svg
   [2.13 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.13.x
-  [2.12 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.12.x
-  [2.12]: https://github.com/doctrine/orm/tree/2.12.x
-  [2.12 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.12.x/graph/badge.svg
-  [2.12 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.12.x

UPGRADE.md

@@ -73,10 +73,6 @@ This method has been deprecated in:
 
 It will be removed in 3.0. Use `getObjectManager()` instead.
 
-## Deprecated `Doctrine\ORM\Event\LifecycleEventArgs` class
-
-It will be removed in 3.0. Use `Doctrine\Persistence\Event\LifecycleEventArgs` instead.
-
 ## Prepare split of output walkers and tree walkers
 
 In 3.0, `SqlWalker` and its child classes won't implement the `TreeWalker`

composer.json

@@ -40,15 +40,15 @@
     },
     "require-dev": {
         "doctrine/annotations": "^1.13",
-        "doctrine/coding-standard": "^9.0",
+        "doctrine/coding-standard": "^9.0.2 || ^10.0",
         "phpbench/phpbench": "^0.16.10 || ^1.0",
-        "phpstan/phpstan": "~1.4.10 || 1.8.2",
+        "phpstan/phpstan": "~1.4.10 || 1.8.5",
         "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
         "psr/log": "^1 || ^2 || ^3",
         "squizlabs/php_codesniffer": "3.7.1",
         "symfony/cache": "^4.4 || ^5.4 || ^6.0",
         "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
-        "vimeo/psalm": "4.26.0"
+        "vimeo/psalm": "4.27.0"
     },
     "conflict": {
         "doctrine/annotations": "<1.13 || >= 2.0"

docs/en/cookbook/strategy-cookbook-introduction.rst

@@ -214,8 +214,8 @@ This might look like this:
 
     <?php
     use Doctrine\Common\EventSubscriber;
+    use Doctrine\ORM\Event\LifecycleEventArgs;
     use Doctrine\ORM\Events;
-    use Doctrine\Persistence\Event\LifecycleEventArgs;
 
     /**
      * The BlockStrategyEventListener will initialize a strategy after the

docs/en/reference/events.rst

@@ -214,7 +214,7 @@ specific to a particular entity class's lifecycle.
 
         <?php
         use Doctrine\DBAL\Types\Types;
-        use Doctrine\Persistence\Event\LifecycleEventArgs;
+        use Doctrine\ORM\Event\LifecycleEventArgs;
 
         #[Entity]
         #[HasLifecycleCallbacks]
@@ -541,7 +541,7 @@ mentioned sets. See this example:
     {
         public function onFlush(OnFlushEventArgs $eventArgs)
         {
-            $em = $eventArgs->getEntityManager();
+            $em = $eventArgs->getObjectManager();
             $uow = $em->getUnitOfWork();
 
             foreach ($uow->getScheduledEntityInsertions() as $entity) {

docs/en/reference/inheritance-mapping.rst

@@ -178,9 +178,9 @@ relationships involving types that employ this mapping strategy are
 very performing.
 
 There is a general performance consideration with Single Table
-Inheritance: If the target-entity of a many-to-one or one-to-one 
-association is an STI entity, it is preferable for performance reasons that it 
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
+Inheritance: If the target-entity of a many-to-one or one-to-one
+association is an STI entity, it is preferable for performance reasons that it
+be a leaf entity in the inheritance hierarchy, (ie. have no subclasses).
 Otherwise Doctrine *CANNOT* create proxy instances
 of this entity and will *ALWAYS* load the entity eagerly.
 
@@ -284,9 +284,9 @@ themselves on access of any subtype fields, so accessing fields of
 subtypes after such a query is not safe.
 
 There is a general performance consideration with Class Table
-Inheritance: If the target-entity of a many-to-one or one-to-one 
-association is a CTI entity, it is preferable for performance reasons that it 
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
+Inheritance: If the target-entity of a many-to-one or one-to-one
+association is a CTI entity, it is preferable for performance reasons that it
+be a leaf entity in the inheritance hierarchy, (ie. have no subclasses).
 Otherwise Doctrine *CANNOT* create proxy instances
 of this entity and will *ALWAYS* load the entity eagerly.
 

docs/en/reference/query-builder.rst

@@ -268,7 +268,7 @@ Doctrine\DBAL\ParameterType::* or a DBAL Type name for conversion.
     use Doctrine\DBAL\Types\Types;
     
     // prevents attempt to load metadata for date time class, improving performance
-    $qb->setParameter('date', new \DateTimeImmutable(), Types::DATE_IMMUTABLE)
+    $qb->setParameter('date', new \DateTimeImmutable(), Types::DATETIME_IMMUTABLE)
 
 If you've got several parameters to bind to your query, you can
 also use setParameters() instead of setParameter() with the

docs/en/reference/working-with-associations.rst

@@ -37,7 +37,7 @@ information about its type and if it's the owning or inverse side.
     {
         /** @Id @GeneratedValue @Column(type="string") */
         private $id;
-    
+
         /**
          * Bidirectional - Many users have Many favorite comments (OWNING SIDE)
          *
@@ -45,7 +45,7 @@ information about its type and if it's the owning or inverse side.
          * @JoinTable(name="user_favorite_comments")
          */
         private $favorites;
-    
+
         /**
          * Unidirectional - Many users have marked many comments as read
          *
@@ -53,14 +53,14 @@ information about its type and if it's the owning or inverse side.
          * @JoinTable(name="user_read_comments")
          */
         private $commentsRead;
-    
+
         /**
          * Bidirectional - One-To-Many (INVERSE SIDE)
          *
          * @OneToMany(targetEntity="Comment", mappedBy="author")
          */
         private $commentsAuthored;
-    
+
         /**
          * Unidirectional - Many-To-One
          *
@@ -68,20 +68,20 @@ information about its type and if it's the owning or inverse side.
          */
         private $firstComment;
     }
-    
+
     /** @Entity */
     class Comment
     {
         /** @Id @GeneratedValue @Column(type="string") */
         private $id;
-    
+
         /**
          * Bidirectional - Many comments are favorited by many users (INVERSE SIDE)
          *
          * @ManyToMany(targetEntity="User", mappedBy="favorites")
          */
         private $userFavorites;
-    
+
         /**
          * Bidirectional - Many Comments are authored by one user (OWNING SIDE)
          *
@@ -100,19 +100,19 @@ definitions omitted):
         firstComment_id VARCHAR(255) DEFAULT NULL,
         PRIMARY KEY(id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE Comment (
         id VARCHAR(255) NOT NULL,
         author_id VARCHAR(255) DEFAULT NULL,
         PRIMARY KEY(id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE user_favorite_comments (
         user_id VARCHAR(255) NOT NULL,
         favorite_comment_id VARCHAR(255) NOT NULL,
         PRIMARY KEY(user_id, favorite_comment_id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE user_read_comments (
         user_id VARCHAR(255) NOT NULL,
         comment_id VARCHAR(255) NOT NULL,
@@ -135,7 +135,7 @@ relations of the ``User``:
         public function getReadComments() {
              return $this->commentsRead;
         }
-    
+
         public function setFirstComment(Comment $c) {
             $this->firstComment = $c;
         }
@@ -148,17 +148,17 @@ The interaction code would then look like in the following snippet
 
     <?php
     $user = $em->find('User', $userId);
-    
+
     // unidirectional many to many
     $comment = $em->find('Comment', $readCommentId);
     $user->getReadComments()->add($comment);
-    
+
     $em->flush();
-    
+
     // unidirectional many to one
     $myFirstComment = new Comment();
     $user->setFirstComment($myFirstComment);
-    
+
     $em->persist($myFirstComment);
     $em->flush();
 
@@ -171,40 +171,40 @@ fields on both sides:
     class User
     {
         // ..
-    
+
         public function getAuthoredComments() {
             return $this->commentsAuthored;
         }
-    
+
         public function getFavoriteComments() {
             return $this->favorites;
         }
     }
-    
+
     class Comment
     {
         // ...
-    
+
         public function getUserFavorites() {
             return $this->userFavorites;
         }
-    
+
         public function setAuthor(User $author = null) {
             $this->author = $author;
         }
     }
-    
+
     // Many-to-Many
     $user->getFavorites()->add($favoriteComment);
     $favoriteComment->getUserFavorites()->add($user);
-    
+
     $em->flush();
-    
+
     // Many-To-One / One-To-Many Bidirectional
     $newComment = new Comment();
     $user->getAuthoredComments()->add($newComment);
     $newComment->setAuthor($user);
-    
+
     $em->persist($newComment);
     $em->flush();
 
@@ -225,10 +225,10 @@ element. Here are some examples:
     // Remove by Elements
     $user->getComments()->removeElement($comment);
     $comment->setAuthor(null);
-    
+
     $user->getFavorites()->removeElement($comment);
     $comment->getUserFavorites()->removeElement($user);
-    
+
     // Remove by Key
     $user->getComments()->remove($ithComment);
     $comment->setAuthor(null);
@@ -240,7 +240,7 @@ Notice how both sides of the bidirectional association are always
 updated. Unidirectional associations are consequently simpler to
 handle.
 
-Also note that if you use type-hinting in your methods, you will 
+Also note that if you use type-hinting in your methods, you will
 have to specify a nullable type, i.e. ``setAddress(?Address $address)``,
 otherwise ``setAddress(null)`` will fail to remove the association.
 Another way to deal with this is to provide a special method, like
@@ -271,8 +271,8 @@ entities that have been re-added to the collection.
 
 Say you clear a collection of tags by calling
 ``$post->getTags()->clear();`` and then call
-``$post->getTags()->add($tag)``. This will not recognize the tag having 
-already been added previously and will consequently issue two separate database 
+``$post->getTags()->add($tag)``. This will not recognize the tag having
+already been added previously and will consequently issue two separate database
 calls.
 
 Association Management Methods
@@ -296,7 +296,7 @@ example that encapsulate much of the association management code:
             // Collections implement ArrayAccess
             $this->commentsRead[] = $comment;
         }
-    
+
         public function addComment(Comment $comment) {
             if (count($this->commentsAuthored) == 0) {
                 $this->setFirstComment($comment);
@@ -304,30 +304,30 @@ example that encapsulate much of the association management code:
             $this->comments[] = $comment;
             $comment->setAuthor($this);
         }
-    
+
         private function setFirstComment(Comment $c) {
             $this->firstComment = $c;
         }
-    
+
         public function addFavorite(Comment $comment) {
             $this->favorites->add($comment);
             $comment->addUserFavorite($this);
         }
-    
+
         public function removeFavorite(Comment $comment) {
             $this->favorites->removeElement($comment);
             $comment->removeUserFavorite($this);
         }
     }
-    
+
     class Comment
     {
         // ..
-    
+
         public function addUserFavorite(User $user) {
             $this->userFavorites[] = $user;
         }
-    
+
         public function removeUserFavorite(User $user) {
             $this->userFavorites->removeElement($user);
         }
@@ -373,7 +373,7 @@ as your preferences.
 Synchronizing Bidirectional Collections
 ---------------------------------------
 
-In the case of Many-To-Many associations you as the developer have the 
+In the case of Many-To-Many associations you as the developer have the
 responsibility of keeping the collections on the owning and inverse side
 in sync when you apply changes to them. Doctrine can only
 guarantee a consistent state for the hydration, not for your client
@@ -387,7 +387,7 @@ can show the possible caveats you can encounter:
     <?php
     $user->getFavorites()->add($favoriteComment);
     // not calling $favoriteComment->getUserFavorites()->add($user);
-    
+
     $user->getFavorites()->contains($favoriteComment); // TRUE
     $favoriteComment->getUserFavorites()->contains($user); // FALSE
 
@@ -422,7 +422,7 @@ comment might look like in your controller (without ``cascade: persist``):
     $user = new User();
     $myFirstComment = new Comment();
     $user->addComment($myFirstComment);
-    
+
     $em->persist($user);
     $em->persist($myFirstComment); // required, if `cascade: persist` is not set
     $em->flush();
@@ -480,7 +480,7 @@ If you then set up the cascading to the ``User#commentsAuthored`` property...
     <?php
     $user = new User();
     $user->comment('Lorem ipsum', new DateTime());
-    
+
     $em->persist($user);
     $em->flush();
 
@@ -559,6 +559,13 @@ OrphanRemoval works with one-to-one, one-to-many and many-to-many associations.
     If you neglect this assumption your entities will get deleted by Doctrine even if
     you assigned the orphaned entity to another one.
 
+.. note::
+
+    ``orphanRemoval=true`` option should be used in combination with ``cascade=["persist"]`` option
+    as the child entity, that is manually persisted, will not be deleted automatically by Doctrine
+    when a collection is still an instance of ArrayCollection (before first flush / hydration).
+    This is a Doctrine limitation since ArrayCollection does not have access to a UnitOfWork.
+
 As a better example consider an Addressbook application where you have Contacts, Addresses
 and StandingData:
 
@@ -578,10 +585,10 @@ and StandingData:
         /** @Id @Column(type="integer") @GeneratedValue */
         private $id;
 
-        /** @OneToOne(targetEntity="StandingData", orphanRemoval=true) */
+        /** @OneToOne(targetEntity="StandingData", cascade={"persist"}, orphanRemoval=true) */
         private $standingData;
 
-        /** @OneToMany(targetEntity="Address", mappedBy="contact", orphanRemoval=true) */
+        /** @OneToMany(targetEntity="Address", mappedBy="contact",  cascade={"persist"}, orphanRemoval=true) */
         private $addresses;
 
         public function __construct()
@@ -612,10 +619,10 @@ Now two examples of what happens when you remove the references:
 
     $em->flush();
 
-In this case you have not only changed the ``Contact`` entity itself but 
-you have also removed the references for standing data and as well as one 
-address reference. When flush is called not only are the references removed 
-but both the old standing data and the one address entity are also deleted 
+In this case you have not only changed the ``Contact`` entity itself but
+you have also removed the references for standing data and as well as one
+address reference. When flush is called not only are the references removed
+but both the old standing data and the one address entity are also deleted
 from the database.
 
 .. _filtering-collections:

lib/Doctrine/ORM/AbstractQuery.php

@@ -198,9 +198,7 @@ abstract class AbstractQuery
         return $this;
     }
 
-    /**
-     * @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise.
-     */
+    /** @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise. */
     public function isCacheable()
     {
         return $this->cacheable;
@@ -228,17 +226,13 @@ abstract class AbstractQuery
         return $this->cacheRegion;
     }
 
-    /**
-     * @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise.
-     */
+    /** @return bool TRUE if the query cache and second level cache are enabled, FALSE otherwise. */
     protected function isCacheEnabled()
     {
         return $this->cacheable && $this->hasCache;
     }
 
-    /**
-     * @return int
-     */
+    /** @return int */
     public function getLifetime()
     {
         return $this->lifetime;
@@ -582,9 +576,7 @@ abstract class AbstractQuery
         return $this;
     }
 
-    /**
-     * @return QueryCacheProfile|null
-     */
+    /** @return QueryCacheProfile|null */
     public function getHydrationCacheProfile()
     {
         return $this->_hydrationCacheProfile;
@@ -834,9 +826,7 @@ abstract class AbstractQuery
         return $this->_expireResultCache;
     }
 
-    /**
-     * @return QueryCacheProfile|null
-     */
+    /** @return QueryCacheProfile|null */
     public function getQueryCacheProfile()
     {
         return $this->_queryCacheProfile;

lib/Doctrine/ORM/Cache/CacheConfiguration.php

@@ -23,41 +23,31 @@ class CacheConfiguration
     /** @var QueryCacheValidator|null */
     private $queryValidator;
 
-    /**
-     * @return CacheFactory|null
-     */
+    /** @return CacheFactory|null */
     public function getCacheFactory()
     {
         return $this->cacheFactory;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setCacheFactory(CacheFactory $factory)
     {
         $this->cacheFactory = $factory;
     }
 
-    /**
-     * @return CacheLogger|null
-     */
+    /** @return CacheLogger|null */
     public function getCacheLogger()
     {
          return $this->cacheLogger;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setCacheLogger(CacheLogger $logger)
     {
         $this->cacheLogger = $logger;
     }
 
-    /**
-     * @return RegionsConfiguration
-     */
+    /** @return RegionsConfiguration */
     public function getRegionsConfiguration()
     {
         if ($this->regionsConfig === null) {
@@ -67,17 +57,13 @@ class CacheConfiguration
         return $this->regionsConfig;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setRegionsConfiguration(RegionsConfiguration $regionsConfig)
     {
         $this->regionsConfig = $regionsConfig;
     }
 
-    /**
-     * @return QueryCacheValidator
-     */
+    /** @return QueryCacheValidator */
     public function getQueryValidator()
     {
         if ($this->queryValidator === null) {
@@ -89,9 +75,7 @@ class CacheConfiguration
          return $this->queryValidator;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setQueryValidator(QueryCacheValidator $validator)
     {
         $this->queryValidator = $validator;

lib/Doctrine/ORM/Cache/CollectionCacheEntry.php

@@ -17,9 +17,7 @@ class CollectionCacheEntry implements CacheEntry
      */
     public $identifiers;
 
-    /**
-     * @param CacheKey[] $identifiers List of entity identifiers hold by the collection
-     */
+    /** @param CacheKey[] $identifiers List of entity identifiers hold by the collection */
     public function __construct(array $identifiers)
     {
         $this->identifiers = $identifiers;

lib/Doctrine/ORM/Cache/CollectionHydrator.php

@@ -20,8 +20,6 @@ interface CollectionHydrator
      */
     public function buildCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, $collection);
 
-    /**
-     * @return mixed[]|null
-     */
+    /** @return mixed[]|null */
     public function loadCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, CollectionCacheEntry $entry, PersistentCollection $collection);
 }

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -262,9 +262,7 @@ class DefaultCache implements Cache
         return $this->queryCaches[$regionName];
     }
 
-    /**
-     * @param mixed $identifier The entity identifier.
-     */
+    /** @param mixed $identifier The entity identifier. */
     private function buildEntityCacheKey(ClassMetadata $metadata, $identifier): EntityCacheKey
     {
         if (! is_array($identifier)) {
@@ -274,9 +272,7 @@ class DefaultCache implements Cache
         return new EntityCacheKey($metadata->rootEntityName, $identifier);
     }
 
-    /**
-     * @param mixed $ownerIdentifier The identifier of the owning entity.
-     */
+    /** @param mixed $ownerIdentifier The identifier of the owning entity. */
     private function buildCollectionCacheKey(
         ClassMetadata $metadata,
         string $association,

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -49,9 +49,7 @@ class DefaultCacheFactory implements CacheFactory
     /** @var string|null */
     private $fileLockRegionDirectory;
 
-    /**
-     * @param CacheItemPoolInterface $cacheItemPool
-     */
+    /** @param CacheItemPoolInterface $cacheItemPool */
     public function __construct(RegionsConfiguration $cacheConfig, $cacheItemPool)
     {
         if ($cacheItemPool instanceof LegacyCache) {
@@ -89,25 +87,19 @@ class DefaultCacheFactory implements CacheFactory
         $this->fileLockRegionDirectory = (string) $fileLockRegionDirectory;
     }
 
-    /**
-     * @return string
-     */
+    /** @return string */
     public function getFileLockRegionDirectory()
     {
         return $this->fileLockRegionDirectory;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setRegion(Region $region)
     {
         $this->regions[$region->getName()] = $region;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setTimestampRegion(TimestampRegion $region)
     {
         $this->timestampRegion = $region;

lib/Doctrine/ORM/Cache/DefaultCollectionHydrator.php

@@ -27,9 +27,7 @@ class DefaultCollectionHydrator implements CollectionHydrator
     /** @var array<string,mixed> */
     private static $hints = [Query::HINT_CACHE_ENABLED => true];
 
-    /**
-     * @param EntityManagerInterface $em The entity manager.
-     */
+    /** @param EntityManagerInterface $em The entity manager. */
     public function __construct(EntityManagerInterface $em)
     {
         $this->em  = $em;

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -38,9 +38,7 @@ class DefaultEntityHydrator implements EntityHydrator
     /** @var array<string,mixed> */
     private static $hints = [Query::HINT_CACHE_ENABLED => true];
 
-    /**
-     * @param EntityManagerInterface $em The entity manager.
-     */
+    /** @param EntityManagerInterface $em The entity manager. */
     public function __construct(EntityManagerInterface $em)
     {
         $this->em                  = $em;

lib/Doctrine/ORM/Cache/Exception/InvalidResultCacheDriver.php

@@ -4,9 +4,7 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-/**
- * @deprecated
- */
+/** @deprecated */
 final class InvalidResultCacheDriver extends CacheException
 {
     public static function create(): self

lib/Doctrine/ORM/Cache/Lock.php

@@ -21,9 +21,7 @@ class Lock
         $this->time  = $time ?: time();
     }
 
-    /**
-     * @return Lock
-     */
+    /** @return Lock */
     public static function createLockRead()
     {
         return new self(uniqid((string) time(), true));

lib/Doctrine/ORM/Cache/Logging/CacheLoggerChain.php

@@ -33,9 +33,7 @@ class CacheLoggerChain implements CacheLogger
         return $this->loggers[$name] ?? null;
     }
 
-    /**
-     * @return array<string, CacheLogger>
-     */
+    /** @return array<string, CacheLogger> */
     public function getLoggers()
     {
         return $this->loggers;

lib/Doctrine/ORM/Cache/Logging/StatisticsCacheLogger.php

@@ -141,25 +141,19 @@ class StatisticsCacheLogger implements CacheLogger
         return $this->cachePutCountMap[$regionName] ?? 0;
     }
 
-    /**
-     * @return array<string, int>
-     */
+    /** @return array<string, int> */
     public function getRegionsMiss()
     {
         return $this->cacheMissCountMap;
     }
 
-    /**
-     * @return array<string, int>
-     */
+    /** @return array<string, int> */
     public function getRegionsHit()
     {
         return $this->cacheHitCountMap;
     }
 
-    /**
-     * @return array<string, int>
-     */
+    /** @return array<string, int> */
     public function getRegionsPut()
     {
         return $this->cachePutCountMap;

lib/Doctrine/ORM/Cache/Persister/Collection/CachedCollectionPersister.php

@@ -16,14 +16,10 @@ use Doctrine\ORM\Persisters\Collection\CollectionPersister;
  */
 interface CachedCollectionPersister extends CachedPersister, CollectionPersister
 {
-    /**
-     * @return ClassMetadata
-     */
+    /** @return ClassMetadata */
     public function getSourceEntityMetadata();
 
-    /**
-     * @return ClassMetadata
-     */
+    /** @return ClassMetadata */
     public function getTargetEntityMetadata();
 
     /**

lib/Doctrine/ORM/Cache/Persister/Collection/ReadWriteCachedCollectionPersister.php

@@ -14,9 +14,7 @@ use function spl_object_id;
 
 class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
 {
-    /**
-     * @param mixed[] $association The association mapping.
-     */
+    /** @param mixed[] $association The association mapping. */
     public function __construct(CollectionPersister $persister, ConcurrentRegion $region, EntityManagerInterface $em, array $association)
     {
         parent::__construct($persister, $region, $em, $association);

lib/Doctrine/ORM/Cache/Persister/Entity/AbstractEntityPersister.php

@@ -177,9 +177,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
         return $this->region;
     }
 
-    /**
-     * @return EntityHydrator
-     */
+    /** @return EntityHydrator */
     public function getEntityHydrator()
     {
         return $this->hydrator;
@@ -207,9 +205,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
         return $cached;
     }
 
-    /**
-     * @param object $entity
-     */
+    /** @param object $entity */
     private function storeJoinedAssociations($entity): void
     {
         if ($this->joinedAssociations === null) {

lib/Doctrine/ORM/Cache/Persister/Entity/CachedEntityPersister.php

@@ -14,9 +14,7 @@ use Doctrine\ORM\Persisters\Entity\EntityPersister;
  */
 interface CachedEntityPersister extends CachedPersister, EntityPersister
 {
-    /**
-     * @return EntityHydrator
-     */
+    /** @return EntityHydrator */
     public function getEntityHydrator();
 
     /**

lib/Doctrine/ORM/Cache/Persister/Entity/NonStrictReadWriteCachedEntityPersister.php

@@ -82,9 +82,7 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
         $this->queuedCache['update'][] = $entity;
     }
 
-    /**
-     * @param object $entity
-     */
+    /** @param object $entity */
     private function updateCache($entity, bool $isChanged): bool
     {
         $class     = $this->metadataFactory->getMetadataFor(get_class($entity));

lib/Doctrine/ORM/Cache/QueryCache.php

@@ -12,9 +12,7 @@ use Doctrine\ORM\Query\ResultSetMapping;
  */
 interface QueryCache
 {
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function clear();
 
     /**
@@ -32,8 +30,6 @@ interface QueryCache
      */
     public function get(QueryCacheKey $key, ResultSetMapping $rsm, array $hints = []);
 
-    /**
-     * @return Region
-     */
+    /** @return Region */
     public function getRegion();
 }

lib/Doctrine/ORM/Cache/QueryCacheKey.php

@@ -34,9 +34,7 @@ class QueryCacheKey extends CacheKey
      */
     public $timestampKey;
 
-    /**
-     * @psalm-param Cache::MODE_* $cacheMode
-     */
+    /** @psalm-param Cache::MODE_* $cacheMode */
     public function __construct(
         string $cacheId,
         int $lifetime = 0,

lib/Doctrine/ORM/Cache/Region/DefaultRegion.php

@@ -31,9 +31,7 @@ use function strtr;
  */
 class DefaultRegion implements Region
 {
-    /**
-     * @internal since 2.11, this constant will be private in 3.0.
-     */
+    /** @internal since 2.11, this constant will be private in 3.0. */
     public const REGION_KEY_SEPARATOR = '_';
     private const REGION_PREFIX       = 'DC2_REGION_';
 
@@ -61,9 +59,7 @@ class DefaultRegion implements Region
     /** @var CacheItemPoolInterface */
     private $cacheItemPool;
 
-    /**
-     * @param CacheItemPoolInterface $cacheItemPool
-     */
+    /** @param CacheItemPoolInterface $cacheItemPool */
     public function __construct(string $name, $cacheItemPool, int $lifetime = 0)
     {
         if ($cacheItemPool instanceof LegacyCache) {

lib/Doctrine/ORM/Cache/Region/FileLockRegion.php

@@ -103,17 +103,13 @@ class FileLockRegion implements ConcurrentRegion
         return $this->directory . DIRECTORY_SEPARATOR . $key->hash . '.' . self::LOCK_EXTENSION;
     }
 
-    /**
-     * @return string|false
-     */
+    /** @return string|false */
     private function getLockContent(string $filename)
     {
         return @file_get_contents($filename);
     }
 
-    /**
-     * @return int|false
-     */
+    /** @return int|false */
     private function getLockTime(string $filename)
     {
         return @fileatime($filename);

lib/Doctrine/ORM/Cache/RegionsConfiguration.php

@@ -31,9 +31,7 @@ class RegionsConfiguration
         $this->defaultLockLifetime = (int) $defaultLockLifetime;
     }
 
-    /**
-     * @return int
-     */
+    /** @return int */
     public function getDefaultLifetime()
     {
         return $this->defaultLifetime;
@@ -49,9 +47,7 @@ class RegionsConfiguration
         $this->defaultLifetime = (int) $defaultLifetime;
     }
 
-    /**
-     * @return int
-     */
+    /** @return int */
     public function getDefaultLockLifetime()
     {
         return $this->defaultLockLifetime;

lib/Doctrine/ORM/Cache/TimestampCacheEntry.php

@@ -17,9 +17,7 @@ class TimestampCacheEntry implements CacheEntry
      */
     public $time;
 
-    /**
-     * @param float|null $time
-     */
+    /** @param float|null $time */
     public function __construct($time = null)
     {
         $this->time = $time ? (float) $time : microtime(true);

lib/Doctrine/ORM/Cache/TimestampCacheKey.php

@@ -9,9 +9,7 @@ namespace Doctrine\ORM\Cache;
  */
 class TimestampCacheKey extends CacheKey
 {
-    /**
-     * @param string $space Result cache id
-     */
+    /** @param string $space Result cache id */
     public function __construct($space)
     {
         $this->hash = (string) $space;

lib/Doctrine/ORM/Configuration.php

@@ -975,9 +975,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
         return $this->_attributes['repositoryFactory'] ?? new DefaultRepositoryFactory();
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isSecondLevelCacheEnabled()
     {
         return $this->_attributes['isSecondLevelCacheEnabled'] ?? false;
@@ -993,17 +991,13 @@ class Configuration extends \Doctrine\DBAL\Configuration
         $this->_attributes['isSecondLevelCacheEnabled'] = (bool) $flag;
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setSecondLevelCacheConfiguration(CacheConfiguration $cacheConfig)
     {
         $this->_attributes['secondLevelCacheConfiguration'] = $cacheConfig;
     }
 
-    /**
-     * @return CacheConfiguration|null
-     */
+    /** @return CacheConfiguration|null */
     public function getSecondLevelCacheConfiguration()
     {
         if (! isset($this->_attributes['secondLevelCacheConfiguration']) && $this->isSecondLevelCacheEnabled()) {

lib/Doctrine/ORM/EntityRepository.php

@@ -65,9 +65,7 @@ class EntityRepository implements ObjectRepository, Selectable
     /** @var Inflector|null */
     private static $inflector;
 
-    /**
-     * @psalm-param ClassMetadata<T> $class
-     */
+    /** @psalm-param ClassMetadata<T> $class */
     public function __construct(EntityManagerInterface $em, ClassMetadata $class)
     {
         $this->_entityName = $class->name;
@@ -306,9 +304,7 @@ class EntityRepository implements ObjectRepository, Selectable
         return $this->getEntityName();
     }
 
-    /**
-     * @return EntityManagerInterface
-     */
+    /** @return EntityManagerInterface */
     protected function getEntityManager()
     {
         return $this->_em;

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -12,15 +12,11 @@ use Doctrine\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
  * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions
  * of entities.
  *
- * @deprecated This class will be removed in ORM 3.0. Use "\Doctrine\Persistence\Event\LifecycleEventArgs" instead.
- *
  * @extends BaseLifecycleEventArgs<EntityManagerInterface>
  */
 class LifecycleEventArgs extends BaseLifecycleEventArgs
 {
-    /**
-     * @param object $object
-     */
+    /** @param object $object */
     public function __construct($object, EntityManagerInterface $objectManager)
     {
         Deprecation::triggerIfCalledFromOutside(

lib/Doctrine/ORM/Event/ListenersInvoker.php

@@ -30,9 +30,6 @@ class ListenersInvoker
      */
     private $eventManager;
 
-    /**
-     * Initializes a new ListenersInvoker instance.
-     */
     public function __construct(EntityManagerInterface $em)
     {
         $this->eventManager = $em->getEventManager();
@@ -46,6 +43,7 @@ class ListenersInvoker
      * @param string        $eventName The entity lifecycle event.
      *
      * @return int Bitmask of subscribed event systems.
+     * @psalm-return int-mask-of<self::INVOKE_*>
      */
     public function getSubscribedSystems(ClassMetadata $metadata, $eventName)
     {
@@ -74,6 +72,7 @@ class ListenersInvoker
      * @param object        $entity    The Entity on which the event occurred.
      * @param EventArgs     $event     The Event args.
      * @param int           $invoke    Bitmask to invoke listeners.
+     * @psalm-param int-mask-of<self::INVOKE_*> $invoke
      *
      * @return void
      */

lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php

@@ -39,9 +39,7 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
         parent::__construct($objectManager);
     }
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setFoundMetadata(?ClassMetadata $classMetadata = null)
     {
         if (func_num_args() < 1) {
@@ -56,9 +54,7 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
         $this->foundMetadata = $classMetadata;
     }
 
-    /**
-     * @return ClassMetadata|null
-     */
+    /** @return ClassMetadata|null */
     public function getFoundMetadata()
     {
         return $this->foundMetadata;

lib/Doctrine/ORM/Event/OnClearEventArgs.php

@@ -20,9 +20,7 @@ class OnClearEventArgs extends BaseOnClearEventArgs
     /** @var string|null */
     private $entityClass;
 
-    /**
-     * @param string|null $entityClass Optional entity class.
-     */
+    /** @param string|null $entityClass Optional entity class. */
     public function __construct(EntityManagerInterface $em, $entityClass = null)
     {
         parent::__construct($em);

lib/Doctrine/ORM/Exception/EntityMissingAssignedId.php

@@ -8,9 +8,7 @@ use function get_debug_type;
 
 final class EntityMissingAssignedId extends ORMException
 {
-    /**
-     * @param object $entity
-     */
+    /** @param object $entity */
     public static function forField($entity, string $field): self
     {
         return new self('Entity of type ' . get_debug_type($entity) . " is missing an assigned ID for field  '" . $field . "'. " .

lib/Doctrine/ORM/Exception/MultipleSelectorsFoundException.php

@@ -11,9 +11,7 @@ final class MultipleSelectorsFoundException extends ORMException
 {
     public const MULTIPLE_SELECTORS_FOUND_EXCEPTION = 'Multiple selectors found: %s. Please select only one.';
 
-    /**
-     * @param string[] $selectors
-     */
+    /** @param string[] $selectors */
     public static function create(array $selectors): self
     {
         return new self(

lib/Doctrine/ORM/Exception/UnknownEntityNamespace.php

@@ -6,9 +6,7 @@ namespace Doctrine\ORM\Exception;
 
 use function sprintf;
 
-/**
- * @deprecated No replacement planned.
- */
+/** @deprecated No replacement planned. */
 final class UnknownEntityNamespace extends ORMException implements ConfigurationException
 {
     public static function fromNamespaceAlias(string $entityNamespaceAlias): self

lib/Doctrine/ORM/Exception/UnrecognizedIdentifierFields.php

@@ -9,9 +9,7 @@ use function sprintf;
 
 final class UnrecognizedIdentifierFields extends ORMException implements ManagerException
 {
-    /**
-     * @param string[] $fieldNames
-     */
+    /** @param string[] $fieldNames */
     public static function fromClassAndFieldNames(string $className, array $fieldNames): self
     {
         return new self(sprintf(

lib/Doctrine/ORM/Id/SequenceGenerator.php

@@ -99,9 +99,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
         return serialize($this->__serialize());
     }
 
-    /**
-     * @return array<string, mixed>
-     */
+    /** @return array<string, mixed> */
     public function __serialize(): array
     {
         return [
@@ -122,9 +120,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
         $this->__unserialize(unserialize($serialized));
     }
 
-    /**
-     * @param array<string, mixed> $data
-     */
+    /** @param array<string, mixed> $data */
     public function __unserialize(array $data): void
     {
         $this->_sequenceName   = $data['sequenceName'];

lib/Doctrine/ORM/Internal/Hydration/AbstractHydrator.php

@@ -464,6 +464,10 @@ abstract class AbstractHydrator
                         break;
                     }
 
+                    if ($value !== null && isset($cacheKeyInfo['enumType'])) {
+                        $value = $this->buildEnum($value, $cacheKeyInfo['enumType']);
+                    }
+
                     $rowData['data'][$dqlAlias][$fieldName] = $type
                         ? $type->convertToPHPValue($value, $this->_platform)
                         : $value;
@@ -547,6 +551,7 @@ abstract class AbstractHydrator
                     'fieldName'    => $fieldName,
                     'type'         => Type::getType($fieldMapping['type']),
                     'dqlAlias'     => $ownerMap,
+                    'enumType'     => $this->_rsm->enumMappings[$key] ?? null,
                 ];
 
                 // the current discriminator value must be saved in order to disambiguate fields hydration,

lib/Doctrine/ORM/Internal/Hydration/HydrationException.php

@@ -11,9 +11,7 @@ use function sprintf;
 
 class HydrationException extends ORMException
 {
-    /**
-     * @return HydrationException
-     */
+    /** @return HydrationException */
     public static function nonUniqueResult()
     {
         return new self('The result returned by the query was not unique.');

lib/Doctrine/ORM/Internal/Hydration/IterableResult.php

@@ -27,9 +27,7 @@ class IterableResult implements Iterator
     /** @var mixed[]|null */
     private $_current = null;
 
-    /**
-     * @param AbstractHydrator $hydrator
-     */
+    /** @param AbstractHydrator $hydrator */
     public function __construct($hydrator)
     {
         $this->_hydrator = $hydrator;
@@ -65,27 +63,21 @@ class IterableResult implements Iterator
         return $this->_current;
     }
 
-    /**
-     * @return mixed
-     */
+    /** @return mixed */
     #[ReturnTypeWillChange]
     public function current()
     {
         return $this->_current;
     }
 
-    /**
-     * @return int
-     */
+    /** @return int */
     #[ReturnTypeWillChange]
     public function key()
     {
         return $this->_key;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     #[ReturnTypeWillChange]
     public function valid()
     {

lib/Doctrine/ORM/Internal/SQLResultCasing.php

@@ -13,9 +13,7 @@ use function method_exists;
 use function strtolower;
 use function strtoupper;
 
-/**
- * @internal
- */
+/** @internal */
 trait SQLResultCasing
 {
     private function getSQLResultCasing(AbstractPlatform $platform, string $column): string

lib/Doctrine/ORM/Mapping/AssociationOverrides.php

@@ -25,9 +25,7 @@ final class AssociationOverrides implements Annotation
      */
     public $overrides = [];
 
-    /**
-     * @param array<AssociationOverride>|AssociationOverride $overrides
-     */
+    /** @param array<AssociationOverride>|AssociationOverride $overrides */
     public function __construct($overrides)
     {
         if (! is_array($overrides)) {

lib/Doctrine/ORM/Mapping/AttributeOverrides.php

@@ -25,9 +25,7 @@ final class AttributeOverrides implements Annotation
      */
     public $overrides = [];
 
-    /**
-     * @param array<AttributeOverride>|AttributeOverride $overrides
-     */
+    /** @param array<AttributeOverride>|AttributeOverride $overrides */
     public function __construct($overrides)
     {
         if (! is_array($overrides)) {

lib/Doctrine/ORM/Mapping/Builder/AssociationBuilder.php

@@ -56,9 +56,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadeAll()
     {
         $this->mapping['cascade'] = ['ALL'];
@@ -66,9 +64,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadePersist()
     {
         $this->mapping['cascade'][] = 'persist';
@@ -76,9 +72,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadeRemove()
     {
         $this->mapping['cascade'][] = 'remove';
@@ -86,9 +80,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadeMerge()
     {
         $this->mapping['cascade'][] = 'merge';
@@ -96,9 +88,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadeDetach()
     {
         $this->mapping['cascade'][] = 'detach';
@@ -106,9 +96,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function cascadeRefresh()
     {
         $this->mapping['cascade'][] = 'refresh';
@@ -116,9 +104,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function fetchExtraLazy()
     {
         $this->mapping['fetch'] = ClassMetadata::FETCH_EXTRA_LAZY;
@@ -126,9 +112,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function fetchEager()
     {
         $this->mapping['fetch'] = ClassMetadata::FETCH_EAGER;
@@ -136,9 +120,7 @@ class AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return $this
-     */
+    /** @return $this */
     public function fetchLazy()
     {
         $this->mapping['fetch'] = ClassMetadata::FETCH_LAZY;

lib/Doctrine/ORM/Mapping/Builder/ClassMetadataBuilder.php

@@ -36,9 +36,7 @@ class ClassMetadataBuilder
         $this->cm = $cm;
     }
 
-    /**
-     * @return ClassMetadataInfo
-     */
+    /** @return ClassMetadataInfo */
     public function getClassMetadata()
     {
         return $this->cm;

lib/Doctrine/ORM/Mapping/Builder/EmbeddedBuilder.php

@@ -17,9 +17,7 @@ class EmbeddedBuilder
     /** @var mixed[] */
     private $mapping;
 
-    /**
-     * @param mixed[] $mapping
-     */
+    /** @param mixed[] $mapping */
     public function __construct(ClassMetadataBuilder $builder, array $mapping)
     {
         $this->builder = $builder;

lib/Doctrine/ORM/Mapping/Builder/FieldBuilder.php

@@ -31,9 +31,7 @@ class FieldBuilder
     /** @var string|null */
     private $customIdGenerator;
 
-    /**
-     * @param mixed[] $mapping
-     */
+    /** @param mixed[] $mapping */
     public function __construct(ClassMetadataBuilder $builder, array $mapping)
     {
         $this->builder = $builder;

lib/Doctrine/ORM/Mapping/Builder/ManyToManyAssociationBuilder.php

@@ -55,9 +55,7 @@ class ManyToManyAssociationBuilder extends OneToManyAssociationBuilder
         return $this;
     }
 
-    /**
-     * @return ClassMetadataBuilder
-     */
+    /** @return ClassMetadataBuilder */
     public function build()
     {
         $mapping              = $this->mapping;

lib/Doctrine/ORM/Mapping/Builder/OneToManyAssociationBuilder.php

@@ -35,9 +35,7 @@ class OneToManyAssociationBuilder extends AssociationBuilder
         return $this;
     }
 
-    /**
-     * @return ClassMetadataBuilder
-     */
+    /** @return ClassMetadataBuilder */
     public function build()
     {
         $mapping = $this->mapping;

lib/Doctrine/ORM/Mapping/ClassMetadataFactory.php

@@ -65,9 +65,7 @@ class ClassMetadataFactory extends AbstractClassMetadataFactory
     /** @var mixed[] */
     private $embeddablesActiveNesting = [];
 
-    /**
-     * @return void
-     */
+    /** @return void */
     public function setEntityManager(EntityManagerInterface $em)
     {
         $this->em = $em;
@@ -659,9 +657,7 @@ DEPRECATION
         }
     }
 
-    /**
-     * @psalm-return ClassMetadata::GENERATOR_TYPE_SEQUENCE|ClassMetadata::GENERATOR_TYPE_IDENTITY
-     */
+    /** @psalm-return ClassMetadata::GENERATOR_TYPE_SEQUENCE|ClassMetadata::GENERATOR_TYPE_IDENTITY */
     private function determineIdGeneratorStrategy(AbstractPlatform $platform): int
     {
         if (

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -574,7 +574,7 @@ class ClassMetadataInfo implements ClassMetadata
      * READ-ONLY: The definition of the discriminator column used in JOINED and SINGLE_TABLE
      * inheritance mappings.
      *
-     * @psalm-var array<string, mixed>|null
+     * @psalm-var array{name: string, fieldName: string, type: string, length?: int, columnDefinition?: string|null}|null
      */
     public $discriminatorColumn;
 
@@ -716,8 +716,8 @@ class ClassMetadataInfo implements ClassMetadata
      * )
      * </code>
      *
-     * @var array<string, mixed>
-     * @psalm-var array{sequenceName: string, allocationSize: string, initialValue: string, quoted?: mixed}
+     * @var array<string, mixed>|null
+     * @psalm-var array{sequenceName: string, allocationSize: string, initialValue: string, quoted?: mixed}|null
      * @todo Merge with tableGeneratorDefinition into generic generatorDefinition
      */
     public $sequenceGeneratorDefinition;
@@ -2323,9 +2323,7 @@ class ClassMetadataInfo implements ClassMetadata
         return $this->generatorType !== self::GENERATOR_TYPE_NONE;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isInheritanceTypeNone()
     {
         return $this->inheritanceType === self::INHERITANCE_TYPE_NONE;
@@ -2378,6 +2376,8 @@ class ClassMetadataInfo implements ClassMetadata
      * Checks whether the class uses a sequence for id generation.
      *
      * @return bool TRUE if the class uses the SEQUENCE generator, FALSE otherwise.
+     *
+     * @psalm-assert-if-true !null $this->sequenceGeneratorDefinition
      */
     public function isIdGeneratorSequence()
     {
@@ -3215,7 +3215,7 @@ class ClassMetadataInfo implements ClassMetadata
      * @see getDiscriminatorColumn()
      *
      * @param mixed[]|null $columnDef
-     * @psalm-param array<string, mixed>|null $columnDef
+     * @psalm-param array{name: string|null, fieldName?: string, type?: string, length?: int, columnDefinition?: string|null}|null $columnDef
      *
      * @return void
      *
@@ -3248,9 +3248,7 @@ class ClassMetadataInfo implements ClassMetadata
         }
     }
 
-    /**
-     * @return array<string, mixed>
-     */
+    /** @return array<string, mixed> */
     final public function getDiscriminatorColumn(): array
     {
         if ($this->discriminatorColumn === null) {
@@ -3845,9 +3843,7 @@ class ClassMetadataInfo implements ClassMetadata
         }
     }
 
-    /**
-     * @throws MappingException
-     */
+    /** @throws MappingException */
     private function assertFieldNotMapped(string $fieldName): void
     {
         if (
@@ -3899,9 +3895,7 @@ class ClassMetadataInfo implements ClassMetadata
         return $sequencePrefix;
     }
 
-    /**
-     * @psalm-param array<string, mixed> $mapping
-     */
+    /** @psalm-param array<string, mixed> $mapping */
     private function assertMappingOrderBy(array $mapping): void
     {
         if (isset($mapping['orderBy']) && ! is_array($mapping['orderBy'])) {
@@ -3909,9 +3903,7 @@ class ClassMetadataInfo implements ClassMetadata
         }
     }
 
-    /**
-     * @psalm-param class-string $class
-     */
+    /** @psalm-param class-string $class */
     private function getAccessibleProperty(ReflectionService $reflService, string $class, string $field): ?ReflectionProperty
     {
         $reflectionProperty = $reflService->getAccessibleProperty($class, $field);

lib/Doctrine/ORM/Mapping/DiscriminatorMap.php

@@ -18,9 +18,7 @@ final class DiscriminatorMap implements Annotation
     /** @var array<int|string, string> */
     public $value;
 
-    /**
-     * @param array<int|string, string> $value
-     */
+    /** @param array<int|string, string> $value */
     public function __construct(array $value)
     {
         $this->value = $value;

lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php

@@ -46,9 +46,7 @@ class AttributeDriver extends CompatibilityAnnotationDriver
      */
     protected $reader;
 
-    /**
-     * @param array<string> $paths
-     */
+    /** @param array<string> $paths */
     public function __construct(array $paths)
     {
         if (PHP_VERSION_ID < 80000) {
@@ -254,10 +252,10 @@ class AttributeDriver extends CompatibilityAnnotationDriver
 
                     $metadata->setDiscriminatorColumn(
                         [
-                            'name'             => $discrColumnAttribute->name,
-                            'type'             => $discrColumnAttribute->type ?: 'string',
-                            'length'           => $discrColumnAttribute->length ?: 255,
-                            'columnDefinition' => $discrColumnAttribute->columnDefinition,
+                            'name'             => isset($discrColumnAttribute->name) ? (string) $discrColumnAttribute->name : null,
+                            'type'             => isset($discrColumnAttribute->type) ? (string) $discrColumnAttribute->type : 'string',
+                            'length'           => isset($discrColumnAttribute->length) ? (int) $discrColumnAttribute->length : 255,
+                            'columnDefinition' => isset($discrColumnAttribute->columnDefinition) ? (string) $discrColumnAttribute->columnDefinition : null,
                         ]
                     );
                 } else {

lib/Doctrine/ORM/Mapping/Driver/AttributeReader.php

@@ -17,9 +17,7 @@ use function is_string;
 use function is_subclass_of;
 use function sprintf;
 
-/**
- * @internal
- */
+/** @internal */
 final class AttributeReader
 {
     /** @var array<class-string<Annotation>,bool> */
@@ -134,9 +132,7 @@ final class AttributeReader
         return $instances;
     }
 
-    /**
-     * @param class-string<Annotation> $attributeClassName
-     */
+    /** @param class-string<Annotation> $attributeClassName */
     private function isRepeatable(string $attributeClassName): bool
     {
         if (isset($this->isRepeatableAttribute[$attributeClassName])) {

lib/Doctrine/ORM/Mapping/Driver/CompatibilityAnnotationDriver.php

@@ -10,16 +10,12 @@ use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use function class_exists;
 
 if (! class_exists(PersistenceAnnotationDriver::class)) {
-    /**
-     * @internal This class will be removed in ORM 3.0.
-     */
+    /** @internal This class will be removed in ORM 3.0. */
     abstract class CompatibilityAnnotationDriver implements MappingDriver
     {
     }
 } else {
-    /**
-     * @internal This class will be removed in ORM 3.0.
-     */
+    /** @internal This class will be removed in ORM 3.0. */
     abstract class CompatibilityAnnotationDriver extends PersistenceAnnotationDriver
     {
     }

lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php

@@ -285,9 +285,7 @@ class DatabaseDriver implements MappingDriver
         }
     }
 
-    /**
-     * @throws MappingException
-     */
+    /** @throws MappingException */
     private function reverseEngineerMappingFromDatabase(): void
     {
         if ($this->tables !== null) {

lib/Doctrine/ORM/Mapping/Driver/PHPDriver.php

@@ -15,9 +15,7 @@ use Doctrine\Persistence\Mapping\Driver\PHPDriver as CommonPHPDriver;
  */
 class PHPDriver extends CommonPHPDriver
 {
-    /**
-     * @param string|string[]|FileLocator $locator
-     */
+    /** @param string|string[]|FileLocator $locator */
     public function __construct($locator)
     {
         Deprecation::trigger(

lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php

@@ -199,7 +199,7 @@ class YamlDriver extends FileDriver
                         [
                             'name' => isset($discrColumn['name']) ? (string) $discrColumn['name'] : null,
                             'type' => isset($discrColumn['type']) ? (string) $discrColumn['type'] : 'string',
-                            'length' => isset($discrColumn['length']) ? (string) $discrColumn['length'] : 255,
+                            'length' => isset($discrColumn['length']) ? (int) $discrColumn['length'] : 255,
                             'columnDefinition' => isset($discrColumn['columnDefinition']) ? (string) $discrColumn['columnDefinition'] : null,
                         ]
                     );

lib/Doctrine/ORM/Mapping/Entity.php

@@ -26,9 +26,7 @@ final class Entity implements Annotation
     /** @var bool */
     public $readOnly = false;
 
-    /**
-     * @psalm-param class-string<EntityRepository<T>>|null $repositoryClass
-     */
+    /** @psalm-param class-string<EntityRepository<T>>|null $repositoryClass */
     public function __construct(?string $repositoryClass = null, bool $readOnly = false)
     {
         $this->repositoryClass = $repositoryClass;

lib/Doctrine/ORM/Mapping/EntityListenerResolver.php

@@ -12,7 +12,7 @@ interface EntityListenerResolver
     /**
      * Clear all instances from the set, or a specific instance when given its identifier.
      *
-     * @param string $className May be any arbitrary string. Name kept for BC only.
+     * @param string|null $className May be any arbitrary string. Name kept for BC only.
      *
      * @return void
      */
@@ -31,6 +31,8 @@ interface EntityListenerResolver
      * Register a entity listener instance.
      *
      * @param object $object An entity listener
+     *
+     * @return void
      */
     public function register($object);
 }

lib/Doctrine/ORM/Mapping/EntityListeners.php

@@ -25,9 +25,7 @@ final class EntityListeners implements Annotation
      */
     public $value = [];
 
-    /**
-     * @param array<string> $value
-     */
+    /** @param array<string> $value */
     public function __construct(array $value = [])
     {
         $this->value = $value;

lib/Doctrine/ORM/Mapping/Exception/InvalidCustomGenerator.php

@@ -16,9 +16,7 @@ final class InvalidCustomGenerator extends ORMException
         return new self('Cannot instantiate custom generator, no class has been defined');
     }
 
-    /**
-     * @param mixed[] $definition
-     */
+    /** @param mixed[] $definition */
     public static function onMissingClass(array $definition): self
     {
         return new self(sprintf(

lib/Doctrine/ORM/Mapping/JoinColumn.php

@@ -43,9 +43,7 @@ final class JoinColumn implements Annotation
     /** @var array<string, mixed> */
     public $options = [];
 
-    /**
-     * @param array<string, mixed> $options
-     */
+    /** @param array<string, mixed> $options */
     public function __construct(
         ?string $name = null,
         string $referencedColumnName = 'id',

lib/Doctrine/ORM/Mapping/JoinTable.php

@@ -30,9 +30,7 @@ final class JoinTable implements Annotation
     /** @var array<string, mixed> */
     public $options = [];
 
-    /**
-     * @param array<string, mixed> $options
-     */
+    /** @param array<string, mixed> $options */
     public function __construct(
         ?string $name = null,
         ?string $schema = null,

lib/Doctrine/ORM/Mapping/MappedSuperclass.php

@@ -22,9 +22,7 @@ final class MappedSuperclass implements Annotation
      */
     public $repositoryClass;
 
-    /**
-     * @psalm-param class-string<EntityRepository>|null $repositoryClass
-     */
+    /** @psalm-param class-string<EntityRepository>|null $repositoryClass */
     public function __construct(?string $repositoryClass = null)
     {
         $this->repositoryClass = $repositoryClass;

lib/Doctrine/ORM/Mapping/MappingException.php

@@ -25,9 +25,7 @@ use const PHP_EOL;
  */
 class MappingException extends ORMException
 {
-    /**
-     * @return MappingException
-     */
+    /** @return MappingException */
     public static function pathRequired()
     {
         return new self('Specifying the paths to your entities is required ' .
@@ -67,9 +65,7 @@ class MappingException extends ORMException
         return new self(sprintf("The inheritance type '%s' specified for '%s' does not exist.", $type, $entityName));
     }
 
-    /**
-     * @return MappingException
-     */
+    /** @return MappingException */
     public static function generatorNotAllowedWithCompositeId()
     {
         return new self("Id generators can't be used with a composite id.");
@@ -924,9 +920,7 @@ class MappingException extends ORMException
         );
     }
 
-    /**
-     * @return self
-     */
+    /** @return self */
     public static function invalidIndexConfiguration($className, $indexName)
     {
         return new self(
@@ -938,9 +932,7 @@ class MappingException extends ORMException
         );
     }
 
-    /**
-     * @return self
-     */
+    /** @return self */
     public static function invalidUniqueConstraintConfiguration($className, $indexName)
     {
         return new self(
@@ -952,9 +944,7 @@ class MappingException extends ORMException
         );
     }
 
-    /**
-     * @param mixed $givenValue
-     */
+    /** @param mixed $givenValue */
     public static function invalidOverrideType(string $expectdType, $givenValue): self
     {
         return new self(sprintf(
@@ -1004,9 +994,7 @@ EXCEPTION
         ), 0, $previous);
     }
 
-    /**
-     * @param LibXMLError[] $errors
-     */
+    /** @param LibXMLError[] $errors */
     public static function fromLibXmlErrors(array $errors): self
     {
         $formatter = static function (LibXMLError $error): string {

lib/Doctrine/ORM/Mapping/OrderBy.php

@@ -18,9 +18,7 @@ final class OrderBy implements Annotation
     /** @var array<string> */
     public $value;
 
-    /**
-     * @param array<string> $value
-     */
+    /** @param array<string> $value */
     public function __construct(array $value)
     {
         $this->value = $value;

lib/Doctrine/ORM/Mapping/ReflectionEmbeddedProperty.php

@@ -31,9 +31,7 @@ class ReflectionEmbeddedProperty extends ReflectionProperty
     /** @var Instantiator|null */
     private $instantiator;
 
-    /**
-     * @param string $embeddedClass
-     */
+    /** @param string $embeddedClass */
     public function __construct(ReflectionProperty $parentProperty, ReflectionProperty $childProperty, $embeddedClass)
     {
         $this->parentProperty = $parentProperty;

lib/Doctrine/ORM/Mapping/ReflectionEnumProperty.php

@@ -21,9 +21,7 @@ class ReflectionEnumProperty extends ReflectionProperty
     /** @var class-string<BackedEnum> */
     private $enumType;
 
-    /**
-     * @param class-string<BackedEnum> $enumType
-     */
+    /** @param class-string<BackedEnum> $enumType */
     public function __construct(ReflectionProperty $originalReflectionProperty, string $enumType)
     {
         $this->originalReflectionProperty = $originalReflectionProperty;

lib/Doctrine/ORM/Mapping/ReflectionReadonlyProperty.php

@@ -14,9 +14,7 @@ use function func_num_args;
 use function is_object;
 use function sprintf;
 
-/**
- * @internal
- */
+/** @internal */
 final class ReflectionReadonlyProperty extends ReflectionProperty
 {
     public function __construct(

lib/Doctrine/ORM/Mapping/UnderscoreNamingStrategy.php

@@ -53,9 +53,7 @@ class UnderscoreNamingStrategy implements NamingStrategy
         $this->pattern = $numberAware ? self::NUMBER_AWARE_PATTERN : self::DEFAULT_PATTERN;
     }
 
-    /**
-     * @return int CASE_LOWER | CASE_UPPER
-     */
+    /** @return int CASE_LOWER | CASE_UPPER */
     public function getCase()
     {
         return $this->case;

lib/Doctrine/ORM/ORMInvalidArgumentException.php

@@ -188,18 +188,14 @@ class ORMInvalidArgumentException extends InvalidArgumentException
             ' to be an entity object, ' . gettype($given) . ' given.');
     }
 
-    /**
-     * @return ORMInvalidArgumentException
-     */
+    /** @return ORMInvalidArgumentException */
     public static function invalidCompositeIdentifier()
     {
         return new self('Binding an entity with a composite primary key to a query is not supported. ' .
             'You should split the parameter into the explicit fields and bind them separately.');
     }
 
-    /**
-     * @return ORMInvalidArgumentException
-     */
+    /** @return ORMInvalidArgumentException */
     public static function invalidIdentifierBindingEntity(/* string $class */)
     {
         if (func_num_args() === 0) {

lib/Doctrine/ORM/PersistentCollection.php

@@ -18,6 +18,7 @@ use function array_diff_key;
 use function array_map;
 use function array_values;
 use function array_walk;
+use function assert;
 use function get_class;
 use function is_object;
 use function spl_object_id;
@@ -33,7 +34,8 @@ use function spl_object_id;
  *
  * @psalm-template TKey of array-key
  * @psalm-template T
- * @template-implements Collection<TKey,T>
+ * @template-extends AbstractLazyCollection<TKey,T>
+ * @template-implements Selectable<TKey,T>
  */
 final class PersistentCollection extends AbstractLazyCollection implements Selectable
 {
@@ -71,7 +73,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      * The name of the field on the target entities that points to the owner
      * of the collection. This is only set if the association is bi-directional.
      *
-     * @var string
+     * @var string|null
      */
     private $backRefFieldName;
 
@@ -131,9 +133,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         return $this->owner;
     }
 
-    /**
-     * @return Mapping\ClassMetadata
-     */
+    /** @return Mapping\ClassMetadata */
     public function getTypeClass(): Mapping\ClassMetadataInfo
     {
         return $this->typeClass;
@@ -148,7 +148,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function hydrateAdd($element): void
     {
-        $this->collection->add($element);
+        $this->unwrap()->add($element);
 
         // If _backRefFieldName is set and its a one-to-many association,
         // we need to set the back reference.
@@ -176,7 +176,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function hydrateSet($key, $element): void
     {
-        $this->collection->set($key, $element);
+        $this->unwrap()->set($key, $element);
 
         // If _backRefFieldName is set, then the association is bidirectional
         // and we need to set the back reference.
@@ -210,7 +210,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function takeSnapshot(): void
     {
-        $this->snapshot = $this->collection->toArray();
+        $this->snapshot = $this->unwrap()->toArray();
         $this->isDirty  = false;
     }
 
@@ -233,7 +233,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function getDeleteDiff(): array
     {
-        $collectionItems = $this->collection->toArray();
+        $collectionItems = $this->unwrap()->toArray();
 
         return array_values(array_diff_key(
             array_combine(array_map('spl_object_id', $this->snapshot), $this->snapshot),
@@ -249,7 +249,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function getInsertDiff(): array
     {
-        $collectionItems = $this->collection->toArray();
+        $collectionItems = $this->unwrap()->toArray();
 
         return array_values(array_diff_key(
             array_combine(array_map('spl_object_id', $collectionItems), $collectionItems),
@@ -322,8 +322,6 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
 
     /**
      * {@inheritdoc}
-     *
-     * @return object
      */
     public function remove($key)
     {
@@ -387,7 +385,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         ) {
             $persister = $this->em->getUnitOfWork()->getCollectionPersister($this->association);
 
-            return $this->collection->containsKey($key) || $persister->containsKey($this, $key);
+            return $this->unwrap()->containsKey($key) || $persister->containsKey($this, $key);
         }
 
         return parent::containsKey($key);
@@ -401,7 +399,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         if (! $this->initialized && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY) {
             $persister = $this->em->getUnitOfWork()->getCollectionPersister($this->association);
 
-            return $this->collection->contains($element) || $persister->contains($this, $element);
+            return $this->unwrap()->contains($element) || $persister->contains($this, $element);
         }
 
         return parent::contains($element);
@@ -432,7 +430,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         if (! $this->initialized && $this->association !== null && $this->association['fetch'] === ClassMetadata::FETCH_EXTRA_LAZY) {
             $persister = $this->em->getUnitOfWork()->getCollectionPersister($this->association);
 
-            return $persister->count($this) + ($this->isDirty ? $this->collection->count() : 0);
+            return $persister->count($this) + ($this->isDirty ? $this->unwrap()->count() : 0);
         }
 
         return parent::count();
@@ -457,7 +455,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function add($value): bool
     {
-        $this->collection->add($value);
+        $this->unwrap()->add($value);
 
         $this->changed();
 
@@ -514,13 +512,13 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
 
     public function isEmpty(): bool
     {
-        return $this->collection->isEmpty() && $this->count() === 0;
+        return $this->unwrap()->isEmpty() && $this->count() === 0;
     }
 
     public function clear(): void
     {
         if ($this->initialized && $this->isEmpty()) {
-            $this->collection->clear();
+            $this->unwrap()->clear();
 
             return;
         }
@@ -536,12 +534,12 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
             // hence for event listeners we need the objects in memory.
             $this->initialize();
 
-            foreach ($this->collection as $element) {
+            foreach ($this->unwrap() as $element) {
                 $uow->scheduleOrphanRemoval($element);
             }
         }
 
-        $this->collection->clear();
+        $this->unwrap()->clear();
 
         $this->initialized = true; // direct call, {@link initialize()} is too expensive
 
@@ -633,7 +631,7 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         }
 
         if ($this->initialized) {
-            return $this->collection->matching($criteria);
+            return $this->unwrap()->matching($criteria);
         }
 
         if ($this->association['type'] === ClassMetadata::MANY_TO_MANY) {
@@ -665,6 +663,8 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     public function unwrap(): Collection
     {
+        assert($this->collection !== null);
+
         return $this->collection;
     }
 
@@ -674,10 +674,10 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
         $newlyAddedDirtyObjects = [];
 
         if ($this->isDirty) {
-            $newlyAddedDirtyObjects = $this->collection->toArray();
+            $newlyAddedDirtyObjects = $this->unwrap()->toArray();
         }
 
-        $this->collection->clear();
+        $this->unwrap()->clear();
         $this->em->getUnitOfWork()->loadCollection($this);
         $this->takeSnapshot();
 
@@ -696,14 +696,14 @@ final class PersistentCollection extends AbstractLazyCollection implements Selec
      */
     private function restoreNewObjectsInDirtyCollection(array $newObjects): void
     {
-        $loadedObjects               = $this->collection->toArray();
+        $loadedObjects               = $this->unwrap()->toArray();
         $newObjectsByOid             = array_combine(array_map('spl_object_id', $newObjects), $newObjects);
         $loadedObjectsByOid          = array_combine(array_map('spl_object_id', $loadedObjects), $loadedObjects);
         $newObjectsThatWereNotLoaded = array_diff_key($newObjectsByOid, $loadedObjectsByOid);
 
         if ($newObjectsThatWereNotLoaded) {
             // Reattach NEW objects added through add(), if any.
-            array_walk($newObjectsThatWereNotLoaded, [$this->collection, 'add']);
+            array_walk($newObjectsThatWereNotLoaded, [$this->unwrap(), 'add']);
 
             $this->isDirty = true;
         }

lib/Doctrine/ORM/Persisters/Collection/ManyToManyPersister.php

@@ -367,9 +367,7 @@ class ManyToManyPersister extends AbstractCollectionPersister
         return $conditions;
     }
 
-    /**
-     * @return string
-     */
+    /** @return string */
     protected function getDeleteSQL(PersistentCollection $collection)
     {
         $columns   = [];
@@ -757,9 +755,7 @@ class ManyToManyPersister extends AbstractCollectionPersister
         return '';
     }
 
-    /**
-     * @throws DBALException
-     */
+    /** @throws DBALException */
     private function getLimitSql(Criteria $criteria): string
     {
         $limit  = $criteria->getMaxResults();

lib/Doctrine/ORM/Persisters/Collection/OneToManyPersister.php

@@ -165,9 +165,7 @@ class OneToManyPersister extends AbstractCollectionPersister
         throw new BadMethodCallException('Filtering a collection by Criteria is not supported by this CollectionPersister.');
     }
 
-    /**
-     * @throws DBALException
-     */
+    /** @throws DBALException */
     private function deleteEntityCollection(PersistentCollection $collection): int
     {
         $mapping     = $collection->getMapping();

lib/Doctrine/ORM/Persisters/Entity/CachedPersisterContext.php

@@ -69,9 +69,7 @@ class CachedPersisterContext
      */
     public $handlesLimits;
 
-    /**
-     * @param bool $handlesLimits
-     */
+    /** @param bool $handlesLimits */
     public function __construct(
         ClassMetadata $class,
         ResultSetMapping $rsm,

lib/Doctrine/ORM/Persisters/Entity/EntityPersister.php

@@ -17,9 +17,7 @@ use Doctrine\ORM\Query\ResultSetMapping;
  */
 interface EntityPersister
 {
-    /**
-     * @return ClassMetadata
-     */
+    /** @return ClassMetadata */
     public function getClassMetadata();
 
     /**

lib/Doctrine/ORM/Persisters/Entity/SingleTablePersister.php

@@ -142,9 +142,7 @@ class SingleTablePersister extends AbstractEntityInheritancePersister
         return $conditionSql . $this->getSelectConditionDiscriminatorValueSQL();
     }
 
-    /**
-     * @return string
-     */
+    /** @return string */
     protected function getSelectConditionDiscriminatorValueSQL()
     {
         $values = [];

lib/Doctrine/ORM/PessimisticLockException.php

@@ -8,9 +8,7 @@ use Doctrine\ORM\Exception\ORMException;
 
 class PessimisticLockException extends ORMException
 {
-    /**
-     * @return PessimisticLockException
-     */
+    /** @return PessimisticLockException */
     public static function lockFailed()
     {
         return new self('The pessimistic lock failed.');

lib/Doctrine/ORM/Proxy/Autoloader.php

@@ -6,9 +6,7 @@ namespace Doctrine\ORM\Proxy;
 
 use Doctrine\Common\Proxy\Autoloader as BaseAutoloader;
 
-/**
- * @deprecated use \Doctrine\Common\Proxy\Autoloader instead
- */
+/** @deprecated use \Doctrine\Common\Proxy\Autoloader instead */
 class Autoloader extends BaseAutoloader
 {
 }

lib/Doctrine/ORM/Query/AST/ArithmeticExpression.php

@@ -17,17 +17,13 @@ class ArithmeticExpression extends Node
     /** @var Subselect|null */
     public $subselect;
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isSimpleArithmeticExpression()
     {
         return (bool) $this->simpleArithmeticExpression;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isSubselect()
     {
         return (bool) $this->subselect;

lib/Doctrine/ORM/Query/AST/ArithmeticFactor.php

@@ -31,17 +31,13 @@ class ArithmeticFactor extends Node
         $this->sign              = $sign;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isPositiveSigned()
     {
         return $this->sign === true;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isNegativeSigned()
     {
         return $this->sign === false;

lib/Doctrine/ORM/Query/AST/ArithmeticTerm.php

@@ -14,9 +14,7 @@ class ArithmeticTerm extends Node
     /** @var mixed[] */
     public $arithmeticFactors;
 
-    /**
-     * @param mixed[] $arithmeticFactors
-     */
+    /** @param mixed[] $arithmeticFactors */
     public function __construct(array $arithmeticFactors)
     {
         $this->arithmeticFactors = $arithmeticFactors;

lib/Doctrine/ORM/Query/AST/CoalesceExpression.php

@@ -14,9 +14,7 @@ class CoalesceExpression extends Node
     /** @var mixed[] */
     public $scalarExpressions = [];
 
-    /**
-     * @param mixed[] $scalarExpressions
-     */
+    /** @param mixed[] $scalarExpressions */
     public function __construct(array $scalarExpressions)
     {
         $this->scalarExpressions = $scalarExpressions;

lib/Doctrine/ORM/Query/AST/ConditionalExpression.php

@@ -14,9 +14,7 @@ class ConditionalExpression extends Node
     /** @var mixed[] */
     public $conditionalTerms = [];
 
-    /**
-     * @param mixed[] $conditionalTerms
-     */
+    /** @param mixed[] $conditionalTerms */
     public function __construct(array $conditionalTerms)
     {
         $this->conditionalTerms = $conditionalTerms;

lib/Doctrine/ORM/Query/AST/ConditionalFactor.php

@@ -17,9 +17,7 @@ class ConditionalFactor extends Node
     /** @var ConditionalPrimary */
     public $conditionalPrimary;
 
-    /**
-     * @param ConditionalPrimary $conditionalPrimary
-     */
+    /** @param ConditionalPrimary $conditionalPrimary */
     public function __construct($conditionalPrimary)
     {
         $this->conditionalPrimary = $conditionalPrimary;

lib/Doctrine/ORM/Query/AST/ConditionalPrimary.php

@@ -17,17 +17,13 @@ class ConditionalPrimary extends Node
     /** @var ConditionalExpression|null */
     public $conditionalExpression;
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isSimpleConditionalExpression()
     {
         return (bool) $this->simpleConditionalExpression;
     }
 
-    /**
-     * @return bool
-     */
+    /** @return bool */
     public function isConditionalExpression()
     {
         return (bool) $this->conditionalExpression;

lib/Doctrine/ORM/Query/AST/ConditionalTerm.php

@@ -14,9 +14,7 @@ class ConditionalTerm extends Node
     /** @var mixed[] */
     public $conditionalFactors = [];
 
-    /**
-     * @param mixed[] $conditionalFactors
-     */
+    /** @param mixed[] $conditionalFactors */
     public function __construct(array $conditionalFactors)
     {
         $this->conditionalFactors = $conditionalFactors;