doctrine · GromNaN · Apr 29, 2025 · Apr 28, 2025 · Apr 28, 2025 · Apr 28, 2025
diff --git a/.github/workflows/static-analysis.yml b/.github/workflows/static-analysis.yml
@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "8.2"
+          - "8.4"
 
     steps:
       - name: "Checkout code"

diff --git a/composer.json b/composer.json
@@ -44,8 +44,9 @@
         "doctrine/orm": "^3.2",
         "jmikola/geojson": "^1.0",
         "phpbench/phpbench": "^1.0.0",
-        "phpstan/phpstan": "~1.10.67",
-        "phpstan/phpstan-phpunit": "^1.0",
+        "phpstan/phpstan": "^2.1",
+        "phpstan/phpstan-deprecation-rules": "^2.0",
+        "phpstan/phpstan-phpunit": "^2.0",
         "phpunit/phpunit": "^10.4",
         "squizlabs/php_codesniffer": "^3.5",
         "symfony/cache": "^5.4 || ^6.0 || ^7.0"

diff --git a/docs/en/cookbook/lookup-reference.rst b/docs/en/cookbook/lookup-reference.rst
@@ -68,7 +68,7 @@ and a date.
         #[Field(type: 'date_immutable')]
         public DateTimeImmutable $date;
 
-        /** @var Collection<Item> */
+        /** @var Collection<int, Item> */
         #[ReferenceMany(
             targetDocument: Item::class,
             cascade: 'all',
@@ -378,7 +378,7 @@ You need to create a new class to hold the result of the aggregation.
         #[Field(type: 'date_immutable')]
         public DateTimeImmutable $date;
 
-        /** @var Collection<Item> */
+        /** @var Collection<int, Item> */
         #[EmbedMany(targetDocument: Item::class)]
         public Collection $items;
 
@@ -631,7 +631,7 @@ but not the user.
         #[Field(type: 'string')]
         public string $name;
 
-        /** @var Collection<UserOrderResult> */
+        /** @var Collection<int, UserOrderResult> */
         #[EmbedMany(targetDocument: UserOrderResult::class)]
         public Collection $orders;
     }
@@ -645,7 +645,7 @@ but not the user.
         #[Field(type: 'date_immutable')]
         public DateTimeImmutable $date;
 
-        /** @var Collection<Item> */
+        /** @var Collection<int, Item> */
         #[EmbedMany(targetDocument: Item::class)]
         public Collection $items;
     }

diff --git a/docs/en/cookbook/simple-search-engine.rst b/docs/en/cookbook/simple-search-engine.rst
@@ -141,7 +141,7 @@ Now you can embed the ``Keyword`` document many times in the ``Product``:
     {
         // ...
 
-        /** @var Collection<Keyword> */
+        /** @var Collection<int, Keyword> */
         #[EmbedMany(targetDocument: Keyword::class)]
         public Collection $keywords;
 

diff --git a/docs/en/reference/aggregation-stage-reference.rst b/docs/en/reference/aggregation-stage-reference.rst
@@ -381,7 +381,7 @@ pipeline stages. Take the following relationship for example:
 
     class Orders
     {
-        /** @var Collection<Item> */
+        /** @var Collection<int, Item> */
         #[ReferenceMany(
             targetDocument: Item::class,
             cascade: 'all',

diff --git a/docs/en/reference/attributes-reference.rst b/docs/en/reference/attributes-reference.rst
@@ -217,7 +217,7 @@ Optional arguments:
 
     class User
     {
-        /** @var Collection<BookTag|SongTag> */
+        /** @var Collection<int, BookTag|SongTag> */
         #[EmbedMany(
             strategy:'set',
             discriminatorField:'type',
@@ -987,7 +987,7 @@ Optional arguments:
 
     class User
     {
-        /** @var Collection<Item> */
+        /** @var Collection<int, Item> */
         #[ReferenceMany(
             strategy: 'set',
             targetDocument: Item::class,

diff --git a/docs/en/reference/bidirectional-references.rst b/docs/en/reference/bidirectional-references.rst
@@ -23,7 +23,7 @@ and changes are tracked and persisted separately. Here is an example:
     {
         // ...
 
-        /** @var Collection<BlogPost> */
+        /** @var Collection<int, BlogPost> */
         #[ReferenceMany(targetDocument: BlogPost::class)]
         private Collection $posts;
     }
@@ -66,7 +66,7 @@ One to Many
     {
         // ...
 
-        /** @var Collection<BlogPost> */
+        /** @var Collection<int, BlogPost> */
         #[ReferenceMany(targetDocument: BlogPost::class, mappedBy: 'user')]
         private Collection $posts;
     }
@@ -189,11 +189,11 @@ Self-Referencing Many to Many
     {
         // ...
 
-        /** @var Collection<User> */
+        /** @var Collection<int, User> */
         #[ReferenceMany(targetDocument: User::class, mappedBy: 'myFriends')]
         public Collection $friendsWithMe;
 
-        /** @var Collection<User> */
+        /** @var Collection<int, User> */
         #[ReferenceMany(targetDocument: User::class, inversedBy: 'friendsWithMe')]
         public Collection $myFriends;
 

diff --git a/docs/en/reference/complex-references.rst b/docs/en/reference/complex-references.rst
@@ -35,11 +35,11 @@ querying by the BlogPost's ID.
     {
         // ...
 
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[ReferenceMany(targetDocument: Comment::class, mappedBy: 'blogPost')]
         private Collection $comments;
 
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[ReferenceMany(
              targetDocument: Comment::class,
              mappedBy: 'blogPost',
@@ -88,7 +88,7 @@ administrators:
 
     class BlogPost
     {
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[ReferenceMany(
              targetDocument: Comment::class,
              mappedBy: 'blogPost',
@@ -109,7 +109,7 @@ call on the Comment repository class to populate the reference.
 
     class BlogPost
     {
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[ReferenceMany(
              targetDocument: Comment::class,
              mappedBy: 'blogPost',

diff --git a/docs/en/reference/custom-collections.rst b/docs/en/reference/custom-collections.rst
@@ -20,7 +20,7 @@ persistence-related features.
     {
         // ...
 
-        /** @var Collection<Section> */
+        /** @var Collection<int, Section> */
         #[EmbedMany(targetDocument: Section::class)]
         public Collection $sections;
 
@@ -55,7 +55,7 @@ and ensuring that your custom class is initialized in the owning class' construc
     {
         // ...
 
-        /** @var Collection<Section> */
+        /** @var Collection<int, Section> */
         #[EmbedMany(
             collectionClass: SectionCollection::class,
             targetDocument: Section::class,

diff --git a/docs/en/reference/embedded-mapping.rst b/docs/en/reference/embedded-mapping.rst
@@ -73,7 +73,7 @@ Embed many documents:
         {
             // ...
 
-            /** @var Collection<PhoneNumber> */
+            /** @var Collection<int, PhoneNumber> */
             #[EmbedMany(targetDocument: Phonenumber::class)]
             private Collection $phoneNumbers;
 
@@ -283,7 +283,7 @@ You can achieve this behavior by using the `storeEmptyArray` option for embedded
         {
             // ...
 
-            /** @var Collection<PhoneNumber> */
+            /** @var Collection<int, PhoneNumber> */
             #[EmbedMany(targetDocument: PhoneNumber::class, storeEmptyArray: true)]
             private Collection $phoneNumbers;
             // ...

diff --git a/docs/en/reference/indexes.rst b/docs/en/reference/indexes.rst
@@ -246,7 +246,7 @@ Now if we had a ``BlogPost`` document with the ``Comment`` document embedded man
         #[Index]
         private string $slug;
 
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $comments;
     }

diff --git a/docs/en/reference/introduction.rst b/docs/en/reference/introduction.rst
@@ -87,7 +87,7 @@ the features.
     #[ODM\Document]
     class Manager extends BaseEmployee
     {
-        /** @var Collection<Project> */
+        /** @var Collection<int, Project> */
         #[ODM\ReferenceMany(targetDocument: Project::class)]
         public Collection $projects;
 

diff --git a/docs/en/reference/priming-references.rst b/docs/en/reference/priming-references.rst
@@ -18,7 +18,7 @@ Consider the following abbreviated model:
     #[Document]
     class User
     {
-        /** @var Collection<Account> */
+        /** @var Collection<int, Account> */
         #[ReferenceMany(targetDocument: Account::class)]
         private Collection $accounts;
     }
@@ -112,7 +112,7 @@ specifying them in the mapping:
     #[Document]
     class User
     {
-        /** @var Collection<Account> */
+        /** @var Collection<int, Account> */
         #[ReferenceMany(targetDocument: Account::class, prime: ['user'])]
         private Collection $accounts;
     }

diff --git a/docs/en/reference/reference-mapping.rst b/docs/en/reference/reference-mapping.rst
@@ -94,7 +94,7 @@ Reference many documents:
         {
             // ...
 
-            /** @var Collection<Account> */
+            /** @var Collection<int, Account> */
             #[ReferenceMany(targetDocument: Account::class)]
             private Collection $accounts;
 
@@ -205,7 +205,7 @@ in each `DBRef`_ object:
         {
             // ..
 
-            /** @var Collection<Album|Song> */
+            /** @var Collection<int, Album|Song> */
             #[ReferenceMany(
                 discriminatorMap: [
                     'album' => Album::class,
@@ -240,7 +240,7 @@ a certain class, you can optionally specify a default discriminator value:
         {
             // ..
 
-            /** @var Collection<Album|Song> */
+            /** @var Collection<int, Album|Song> */
             #[ReferenceMany(
                 discriminatorMap: [
                     'album' => Album::class,
@@ -453,7 +453,7 @@ You can achieve this behavior by using the `storeEmptyArray` option.
         {
             // ...
 
-            /** @var Collection<Account> */
+            /** @var Collection<int, Account> */
             #[ReferenceMany(targetDocument: Account::class, storeEmptyArray: true)]
             private Collection $accounts;
 

diff --git a/docs/en/reference/trees.rst b/docs/en/reference/trees.rst
@@ -23,7 +23,7 @@ Full Tree in Single Document
         #[Field(type: 'string')]
         private string $body;
 
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $comments;
 
@@ -39,7 +39,7 @@ Full Tree in Single Document
         #[Field(type: 'string')]
         private string $text;
 
-        /** @var Collection<Comment> */
+        /** @var Collection<int, Comment> */
         #[EmbedMany(targetDocument: Comment::class)]
         private Collection $replies;
 
@@ -115,7 +115,7 @@ Child Reference
         #[Field(type: 'string')]
         private string $name;
 
-        /** @var Collection<Category> */
+        /** @var Collection<int, Category> */
         #[ReferenceMany(targetDocument: Category::class)]
         #[Index]
         private Collection $children;
@@ -172,12 +172,12 @@ Array of Ancestors
         #[Id]
         private string $id;
 
-        /** @var Collection<Category> */
+        /** @var Collection<int, Category> */
         #[ReferenceMany(targetDocument: Category::class)]
         #[Index]
         private Collection $ancestors;
 
-        /** @var Collection<Category> */
+        /** @var Collection<int, Category> */
         #[ReferenceOne(targetDocument: Category::class)]
         #[Index]
         private ?Category $parent = null;

diff --git a/docs/en/reference/working-with-objects.rst b/docs/en/reference/working-with-objects.rst
@@ -423,7 +423,7 @@ in the $addresses collection.
     class User
     {
         //...
-        /** @var Collection<Address> */
+        /** @var Collection<int, Address> */
         #[ReferenceMany(targetDocument: Address::class, cascade: ['persist', 'remove'])]
         private Collection $addresses;
         //...

diff --git a/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php b/lib/Doctrine/ODM/MongoDB/Aggregation/Expr.php
@@ -78,6 +78,7 @@ class Expr implements
     /** @var array{case: mixed|self, then?: mixed|self}|null */
     private ?array $switchBranch = null;
 
+    /** @final This constructor is used in {@see self::expr()} */
     public function __construct(private DocumentManager $dm, private ClassMetadata $class)
     {
     }

diff --git a/lib/Doctrine/ODM/MongoDB/Configuration.php b/lib/Doctrine/ODM/MongoDB/Configuration.php
@@ -286,8 +286,6 @@ public function getAutoGenerateProxyClasses(): int
      * during each script execution.
      *
      * @param self::AUTOGENERATE_* $mode
-     *
-     * @throws InvalidArgumentException If an invalid mode was given.
      */
     public function setAutoGenerateProxyClasses(int $mode): void
     {

diff --git a/lib/Doctrine/ODM/MongoDB/Tools/Console/Command/Schema/CreateCommand.php b/lib/Doctrine/ODM/MongoDB/Tools/Console/Command/Schema/CreateCommand.php
@@ -72,8 +72,10 @@ private function doExecute(InputInterface $input, OutputInterface $output): int
 
             try {
                 if (isset($class)) {
+                    // @phpstan-ignore arguments.count, arguments.count
                     $this->{'processDocument' . $method}($sm, $class, $this->getMaxTimeMsFromInput($input), $this->getWriteConcernFromInput($input), $background);
                 } else {
+                    // @phpstan-ignore arguments.count, arguments.count
                     $this->{'process' . $method}($sm, $this->getMaxTimeMsFromInput($input), $this->getWriteConcernFromInput($input), $background);
                 }
 

diff --git a/lib/Doctrine/ODM/MongoDB/Tools/Console/Command/Schema/DropCommand.php b/lib/Doctrine/ODM/MongoDB/Tools/Console/Command/Schema/DropCommand.php
@@ -72,8 +72,10 @@ private function doExecute(InputInterface $input, OutputInterface $output): int
 
             try {
                 if (is_string($class)) {
+                    // @phpstan-ignore arguments.count
                     $this->{'processDocument' . $method}($sm, $class, $this->getMaxTimeMsFromInput($input), $this->getWriteConcernFromInput($input));
                 } else {
+                    // @phpstan-ignore arguments.count
                     $this->{'process' . $method}($sm, $this->getMaxTimeMsFromInput($input), $this->getWriteConcernFromInput($input));
                 }
 

diff --git a/lib/Doctrine/ODM/MongoDB/Tools/Console/MetadataFilter.php b/lib/Doctrine/ODM/MongoDB/Tools/Console/MetadataFilter.php
@@ -16,6 +16,8 @@
 
 /**
  * Used by CLI Tools to restrict entity-based commands to given patterns.
+ *
+ * @extends FilterIterator<int, ClassMetadata<object>, ArrayIterator>
  */
 class MetadataFilter extends FilterIterator implements Countable
 {

diff --git a/lib/Doctrine/ODM/MongoDB/UnitOfWork.php b/lib/Doctrine/ODM/MongoDB/UnitOfWork.php
@@ -255,6 +255,7 @@ final class UnitOfWork implements PropertyChangedListener
      * The document persister instances used to persist document instances.
      *
      * @var array<class-string, Persisters\DocumentPersister>
+     * @phpstan-ignore missingType.generics
      */
     private array $persisters = [];
 
@@ -1749,7 +1750,7 @@ public function persist(object $document): void
      * NOTE: This method always considers documents that are not yet known to
      * this UnitOfWork as NEW.
      *
-     * @param array<string, object> $visited
+     * @param array<int, object> $visited
      *
      * @throws InvalidArgumentException
      * @throws MongoDBException
@@ -1952,7 +1953,7 @@ private function doMerge(object $document, array &$visited, ?object $prevManaged
                 $prop = $this->reflectionService->getAccessibleProperty($class->name, $name);
                 assert($prop instanceof ReflectionProperty);
 
-                if (method_exists($prop, 'isInitialized') && ! $prop->isInitialized($document)) {
+                if (! $prop->isInitialized($document)) {
                     continue;
                 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,7 +16,7 @@ jobs: @@
         strategy:
           matrix:
             php-version:
-              - "8.2"
+              - "8.4"
         steps:
           - name: "Checkout code"
@@ Expand Down @@