feat: add head and tail methods

composer.json

@@ -22,13 +22,15 @@
     }
   ],
   "require": {
-    "php": ">=7.2",
+    "php": ">=7.4",
     "transprime-research/piper": "^2.0"
   },
   "require-dev": {
     "phpunit/phpunit": ">=8.0",
     "squizlabs/php_codesniffer": "3.*",
-    "illuminate/support": ">=5.5"
+    "illuminate/support": ">=5.5",
+    "ext-json": "*",
+    "symfony/var-dumper": "^6.4"
   },
   "autoload": {
     "psr-4": {

src/Arrayed.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Transprime\Arrayed;
 
 use Closure;
@@ -13,7 +15,7 @@ class Arrayed implements ArrayedInterface
 {
     use ArrayPrefix;
 
-    private $raw;
+    private array $raw;
 
     private $result;
 
@@ -24,7 +26,7 @@ public function __construct(...$values)
         $this->setResult(new Undefined());
     }
 
-    private function argumentsToArray(...$values)
+    private function argumentsToArray(...$values): array
     {
         if (func_num_args() === 1 && is_array($values[0])) {
             return $values[0];
@@ -186,7 +188,11 @@ private function getWorkableItem(bool $asArray = false)
             return $this->raw;
         }
 
-        return ($asArray && !is_array($this->result)) ? (array)$this->result : $this->result;
+        if ($asArray && !is_array($this->result)) {
+            return (array)$this->result;
+        }
+
+        return $this->result;
     }
 
     private static function makeArrayed($data)

src/Traits/ArrayPrefix.php

@@ -1,16 +1,20 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Transprime\Arrayed\Traits;
 
 use Transprime\Arrayed\Exceptions\ArrayedException;
 use Transprime\Arrayed\Interfaces\ArrayedInterface;
+use Transprime\Arrayed\Types\Undefined;
 
 /**
  * Trait ArrayPrefix
  * @package Transprime\Arrayed\Traits
  *
  * @method self combine(array $values)
  * @method mixed shift()
+ * @method mixed pop()
  * @method self slice(int $offset, int $length = null, bool $preserve_keys = false)
  */
 trait ArrayPrefix
@@ -77,6 +81,39 @@ public function keysExists(array $needles, bool $all = true): bool
             : (!$intersect->empty());
     }
 
+    /**
+     * @throws ArrayedException
+     * @return ArrayedInterface|mixed
+     */
+    public function head(bool $preserveKeys = false)
+    {
+        return self::makeArrayed(
+            $this->when($this->getWorkableItem())
+                ->slice(0, 1, $preserveKeys)
+                ->values()
+                ->offsetGet(0)
+        );
+    }
+
+    public function tail(): ArrayedInterface
+    {
+        return $this->when($this->getWorkableItem())
+            ->slice(1);
+    }
+
+    private function when($truthyValue, $default = Undefined::class)
+    {
+        if ($truthyValue) {
+            return $this;
+        }
+
+        if ($default === Undefined::class || $default instanceof Undefined) {
+            throw new \InvalidArgumentException('Value cannot be resolved');
+        }
+
+        return $this->setResult($default);
+    }
+
     /**
      * Forward the calls to `array_*` that is not yet implemented
      * <br>

tests/ArrayPrefixTraitTest.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Transprime\Arrayed\Tests;
 
 use PHPUnit\Framework\TestCase;
@@ -159,5 +161,63 @@ public function testUnImplementedArrayPrefixFunction()
             array_combine($keys, $values),
             arrayed($keys)->combine($values)->result()
         );
+
+        // array_pop
+        $data = ['a' => 'b', 'c' => 'd'];
+
+        $this->assertEquals(
+            'd',
+            arrayed($data)->pop(),
+        );
+
+        // array_shift.
+        $this->assertEquals(
+            'b',
+            $arr = arrayed($data)->shift(),
+        );
+    }
+
+    public function testHead(): void
+    {
+        $data = ['a', 'b', 'c', 'd'];
+
+        $this->assertSame(
+            'a',
+            arrayed($data)->head(),
+        );
+
+        $data = ['a' => 'b', 'c' => 'd'];
+
+        $this->assertSame(
+            'b',
+            arrayed($data)->head(),
+        );
+
+        // Test empty.
+        $this->expectException(\InvalidArgumentException::class);
+
+        arrayed([])->head();
+    }
+
+    public function testTail(): void
+    {
+        $data = ['a', 'b', 'c', 'd'];
+
+        $this->assertSame(
+            ['b', 'c', 'd'],
+            arrayed($data)->tail()->result(),
+        );
+
+        $data = ['a' => 'b', 'c' => 'd'];
+
+        $this->assertSame(
+            ['c' => 'd'],
+            arrayed($data)->tail()->result(),
+        );
+
+        // Test empty.
+        $this->expectException(\InvalidArgumentException::class);
+
+        arrayed([])->tail();
     }
 }

tests/ArrayedTest.php

@@ -1,5 +1,7 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Transprime\Arrayed\Tests;
 
 use PHPUnit\Framework\TestCase;
@@ -325,8 +327,8 @@ public function testJsonable()
     {
         $data = ['a' => 1, 'b' => 2];
 
-        $this->assertJson(arrayed($data));
-        $this->assertStringContainsString(arrayed($data), json_encode($data));
+        $this->assertJson((string) arrayed($data));
+        $this->assertStringContainsString((string) arrayed($data), json_encode($data));
         $this->assertEquals(json_encode($data), arrayed($data));
         $this->assertSame(json_encode($data), json_encode(arrayed($data)));
     }