Merge branch '2.16.x' into merge-2.16-into-3.0

Author: GromNaN

composer.json

@@ -29,7 +29,7 @@
         "php": "^8.4",
         "ext-mongodb": "^2.1",
         "composer-runtime-api": "^2.0",
-        "doctrine/collections": "^1.5 || ^2.0",
+        "doctrine/collections": "^2.1",
         "doctrine/event-manager": "^1.0 || ^2.0",
         "doctrine/instantiator": "^1.1 || ^2",
         "doctrine/persistence": "^3.2 || ^4",

src/PersistentCollection/PersistentCollectionTrait.php

@@ -4,11 +4,9 @@
 
 namespace Doctrine\ODM\MongoDB\PersistentCollection;
 
-use BadMethodCallException;
 use Closure;
 use Doctrine\Common\Collections\Collection as BaseCollection;
 use Doctrine\Common\Collections\Criteria;
-use Doctrine\Common\Collections\ReadableCollection;
 use Doctrine\Common\Collections\Selectable;
 use Doctrine\ODM\MongoDB\DocumentManager;
 use Doctrine\ODM\MongoDB\Mapping\ClassMetadata;
@@ -25,7 +23,7 @@
 use function array_values;
 use function count;
 use function is_object;
-use function method_exists;
+use function sprintf;
 
 /**
  * Trait with methods needed to implement PersistentCollectionInterface.
@@ -437,8 +435,15 @@ public function set(string|int $key, mixed $value): void
         $this->doSet($key, $value, false);
     }
 
-    /** @param T $element */
-    public function add(mixed $element): bool
+    /**
+     * Adds an element at the end of the collection.
+     *
+     * @param mixed $element The element to add.
+     * @phpstan-param T $element
+     *
+     * @return true The return value is kept for BC reasons, but will be void in doctrine/mongodb-odm 3.0.
+     */
+    public function add($element): bool
     {
         return $this->doAdd($element, false);
     }
@@ -750,10 +755,6 @@ private function isOrphanRemovalEnabled(): bool
      */
     public function findFirst(Closure $p): ?object
     {
-        if (! method_exists($this->coll, 'findFirst')) {
-            throw new BadMethodCallException('findFirst() is only available since doctrine/collections v2');
-        }
-
         return $this->coll->findFirst($p);
     }
 
@@ -768,21 +769,24 @@ public function findFirst(Closure $p): ?object
      */
     public function reduce(Closure $func, mixed $initial = null): mixed
     {
-        if (! method_exists($this->coll, 'reduce')) {
-            throw new BadMethodCallException('reduce() is only available since doctrine/collections v2');
-        }
-
         return $this->coll->reduce($func, $initial);
     }
 
-    public function matching(Criteria $criteria): ReadableCollection
+    /** @return BaseCollection<TKey, T> */
+    public function matching(Criteria $criteria): BaseCollection
     {
         $this->initialize();
 
         if (! $this->coll instanceof Selectable) {
             throw new LogicException('The backed collection must implement Selectable to use matching().');
         }
 
-        return $this->coll->matching($criteria);
+        $coll = $this->coll->matching($criteria);
+
+        if (! $coll instanceof BaseCollection) {
+            throw new LogicException(sprintf('The matching() method of the backed collection must return an instance of "%s".', BaseCollection::class));
+        }
+
+        return $coll;
     }
 }

tests/Tests/PersistentCollectionTest.php

@@ -341,7 +341,7 @@ public function testMatchingIsForwarded(): void
         $expectedResult = new ArrayCollection([new stdClass()]);
 
         // ArrayCollection implements both Collection and Selectable
-        // When doctrine/collections 2.6+ is required, we can mock Collection directly
+        // When doctrine/collections 3.0 is required, we can mock Collection directly
         $collection = $this->createMock(ArrayCollection::class);
         $collection->expects($this->once())
             ->method('matching')