Add first() method

Author: Jarek Jakubowski

src/JarJak/Collection/Collection.php

@@ -120,6 +120,17 @@ public function sort(?callable $comparator = null): self
         return static::from($array);
     }
 
+    public function first()
+    {
+        if ($this instanceof \IteratorAggregate) {
+            // PHP 8: SplFixedArray no longer implements Iterator
+            $this->getIterator()->rewind();
+            return $this->getIterator()->current() ?: null;
+        }
+        $this->rewind();
+        return $this->current() ?: null;
+    }
+
     public function jsonSerialize(): array
     {
         return $this->toArray();

tests/CollectionTest.php

@@ -93,4 +93,17 @@ public function __construct(\DateTimeInterface ...$items)
 
         $this->assertSame($expected, $result->toArray());
     }
+
+    public function testFirst(): void
+    {
+        $collection = Collection::from(range(1, 10));
+        $sum = 0;
+        foreach ($collection as $item) {
+            // just iterate over it
+            $sum += $item;
+        }
+
+        $this->assertSame($collection->first(), 1);
+        $this->assertSame(55, $sum);
+    }
 }