feat: add find and findLast functions

Author: Bl00D4NGEL

src/Domain/Collection.php

@@ -23,13 +23,14 @@
 /**
  * @template T of object
  * @implements IteratorAggregate<T>
- * @implements ArrayAccess<mixed, T>
+ * @implements ArrayAccess<array-key, T>
  */
 class Collection implements ArrayAccess, Countable, IteratorAggregate
 {
     /**
      * @param T[] $items
      * @param class-string<T>|null $itemType
+     * @throws Assert\AssertionFailedException
      */
     final public function __construct(
         private readonly array $items = [],
@@ -131,6 +132,42 @@ public function some(callable $callback = null): bool
         return false;
     }
 
+    /**
+     * Returns the first element of the collection that matches the given callback or null if the collection is empty
+     * or the callback never returned true for any item
+     *
+     * @param callable(T, int, static): bool $callback
+     * @return ?T
+     */
+    public function find(callable $callback)
+    {
+        foreach ($this->items as $index => $item) {
+            if ($callback($item, $index, $this)) {
+                return $item;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Returns the last element of the collection that matches the given callback or null if the collection is empty
+     * or the callback never returned true for any item
+     *
+     * @param callable(T, int, static): bool $callback
+     * @return ?T
+     */
+    public function findLast(callable $callback)
+    {
+        foreach (array_reverse($this->items) as $index => $item) {
+            if ($callback($item, $index, $this)) {
+                return $item;
+            }
+        }
+
+        return null;
+    }
+
     /**
      * Returns the first element of the collection that matches the given callback.
      * If no callback is given the first element in the collection is returned.

tests/Domain/CollectionTest.php

@@ -433,6 +433,52 @@ public function testSomeShortCircuitsOnFirstFalsyValue(): void
         });
     }
 
+    public function testFind(): void
+    {
+        $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $collection = new Collection($items);
+
+        $this->assertSame(3, $collection->find(static fn ($item) => $item > 2));
+    }
+
+    public function testFindReturnsNullIfCallbackNeverReturnsTrue(): void
+    {
+        $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $collection = new Collection($items);
+
+        $this->assertSame(null, $collection->find(static fn () => false));
+    }
+
+    public function testFindReturnsNullOnEmptyCollection(): void
+    {
+        $collection = new Collection([]);
+
+        $this->assertSame(null, $collection->find(static fn () => true));
+    }
+
+    public function testFindLast(): void
+    {
+        $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $collection = new Collection($items);
+
+        $this->assertSame(10, $collection->findLast(static fn ($item) => $item > 2));
+    }
+
+    public function testFindLastReturnsNullIfCallbackNeverReturnsTrue(): void
+    {
+        $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+        $collection = new Collection($items);
+
+        $this->assertSame(null, $collection->findLast(static fn () => false));
+    }
+
+    public function testFindLastReturnsNullOnEmptyCollection(): void
+    {
+        $collection = new Collection([]);
+
+        $this->assertSame(null, $collection->find(static fn () => true));
+    }
+
     public function testFirst(): void
     {
         $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
@@ -477,7 +523,7 @@ public function testFirstOrReturnsFallbackValueIfCallbackIsNeverSatisfied(): voi
     {
         $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
         $collection = new Collection($items);
-        $this->assertSame(-1, $collection->firstOr(static fn ($item) => $item > 10, -1));
+        $this->assertSame(-1, $collection->firstOr(static fn () => false, -1));
     }
 
     public function testLast(): void
@@ -524,7 +570,7 @@ public function testLastOrReturnsFallbackValueIfCallbackIsNeverSatisfied(): void
     {
         $items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
         $collection = new Collection($items);
-        $this->assertSame(-1, $collection->lastOr(static fn ($item) => $item > 10, -1));
+        $this->assertSame(-1, $collection->lastOr(static fn () => false, -1));
     }
 
     public function testIsEmpty(): void