From 7f86e63e7a08513453d91c9a9707056c0864f09f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maximilian=20B=C3=B6sing?=
 <2189546+boesing@users.noreply.github.com>
Date: Wed, 17 Aug 2022 17:28:12 +0200
Subject: [PATCH] feature: ensure that `Selectable#matching` always returns an
 instance of `Collection`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Maximilian Bösing <2189546+boesing@users.noreply.github.com>
---
 lib/Doctrine/Common/Collections/Selectable.php    |  4 ++--
 .../Common/Collections/BaseCollectionTest.php     | 15 +++++++++++++++
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/lib/Doctrine/Common/Collections/Selectable.php b/lib/Doctrine/Common/Collections/Selectable.php
index ddc73bb69..9f7586de3 100644
--- a/lib/Doctrine/Common/Collections/Selectable.php
+++ b/lib/Doctrine/Common/Collections/Selectable.php
@@ -23,8 +23,8 @@ interface Selectable
      * Selects all elements from a selectable that match the expression and
      * returns a new collection containing these elements.
      *
-     * @return Collection<mixed>
-     * @psalm-return Collection<TKey,T>
+     * @return Collection<mixed>&Selectable<mixed>
+     * @psalm-return Collection<TKey,T>&Selectable<TKey,T>
      */
     public function matching(Criteria $criteria);
 }
diff --git a/tests/Doctrine/Tests/Common/Collections/BaseCollectionTest.php b/tests/Doctrine/Tests/Common/Collections/BaseCollectionTest.php
index 09249527c..61d0c200f 100644
--- a/tests/Doctrine/Tests/Common/Collections/BaseCollectionTest.php
+++ b/tests/Doctrine/Tests/Common/Collections/BaseCollectionTest.php
@@ -3,6 +3,8 @@
 namespace Doctrine\Tests\Common\Collections;
 
 use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Collections\Criteria;
+use Doctrine\Common\Collections\Selectable;
 use PHPUnit\Framework\TestCase;
 use stdClass;
 
@@ -10,6 +12,7 @@
 use function is_array;
 use function is_numeric;
 use function is_string;
+use function sprintf;
 
 abstract class BaseCollectionTest extends TestCase
 {
@@ -237,4 +240,16 @@ public function testCanVerifyExistingKeysWithNullValues(): void
         $this->collection->set('key', null);
         self::assertTrue($this->collection->containsKey('key'));
     }
+
+    public function testMatchingAlwaysReturnsCollection(): void
+    {
+        if (! $this->collection instanceof Selectable) {
+            self::markTestSkipped(sprintf('Collection does not implement %s', Selectable::class));
+        }
+
+        $criteria = Criteria::create();
+
+        self::assertInstanceOf(Collection::class, $this->collection->matching($criteria));
+        self::assertInstanceOf(Selectable::class, $this->collection->matching($criteria));
+    }
 }