Add getFirst() and getLast()

changelog.md

@@ -1,5 +1,7 @@
 ### master
 
+- Add `AbstractCollection::getFirst()` and `AbstractCollection::getLast()`
+
 ### [6.1.0](../../compare/6.0.1...6.1.0) - 2024-05-24
 
 - Add support for Symfony `7.0`

src/AbstractCollection.php

@@ -191,6 +191,28 @@ public function merge(CollectionInterface $collection): static
         return $this->replace(array_merge($this->values, $collection->toArray()));
     }
 
+    /** @return TValueType */
+    public function getFirst(): mixed
+    {
+        $key = array_key_first($this->values);
+        if (is_null($key)) {
+            throw new KeyNotFoundException('First key not found.');
+        }
+
+        return $this->get($key);
+    }
+
+    /** @return TValueType */
+    public function getLast(): mixed
+    {
+        $key = array_key_last($this->values);
+        if (is_null($key)) {
+            throw new KeyNotFoundException('Last key not found.');
+        }
+
+        return $this->get($key);
+    }
+
     protected function assertIsNotReadOnly(): static
     {
         if ($this->isReadOnly()) {

tests/Unit/AbstractCollection/GeLastTest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Steevanb\PhpCollection\Tests\Unit\AbstractCollection;
+
+use PHPUnit\Framework\TestCase;
+use Steevanb\PhpCollection\Exception\KeyNotFoundException;
+
+final class GeLastTest extends TestCase
+{
+    public function testCount0(): void
+    {
+        $collection = new Collection();
+
+        $this->expectExceptionObject(new KeyNotFoundException('Last key not found.'));
+        $collection->getLast();
+    }
+
+    public function testIndexed(): void
+    {
+        $collection = new Collection(['foo', 'bar']);
+
+        static::assertSame('bar', $collection->getLast());
+    }
+
+    public function testAssociative(): void
+    {
+        $collection = new Collection(['foo' => 'bar', 'baz' => 'qux']);
+
+        static::assertSame('qux', $collection->getLast());
+    }
+}

tests/Unit/AbstractCollection/GetFirstTest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Steevanb\PhpCollection\Tests\Unit\AbstractCollection;
+
+use PHPUnit\Framework\TestCase;
+use Steevanb\PhpCollection\Exception\KeyNotFoundException;
+
+final class GetFirstTest extends TestCase
+{
+    public function testCount0(): void
+    {
+        $collection = new Collection();
+
+        $this->expectExceptionObject(new KeyNotFoundException('First key not found.'));
+        $collection->getFirst();
+    }
+
+    public function testIndexed(): void
+    {
+        $collection = new Collection(['foo', 'bar']);
+
+        static::assertSame('foo', $collection->getFirst());
+    }
+
+    public function testAssociative(): void
+    {
+        $collection = new Collection(['foo' => 'bar', 'baz' => 'qux']);
+
+        static::assertSame('bar', $collection->getFirst());
+    }
+}