Add getDeeply macro (#220)

* getDeeply method

* register macro

* add tests

* update readme

* Fix styling

* fix description

* fix docblock params

Co-authored-by: michael-rubel <[email protected]>

README.md

@@ -51,6 +51,7 @@ The package will automatically register itself.
 - [`firstOrFail`](#firstorfail)
 - [`firstOrPush`](#firstorpush)
 - [`fromPairs`](#frompairs)
+- [`getDeeply`](#getdeeply)
 - [`glob`](#glob)
 - [`groupByModel`](#groupbymodel)
 - [`head`](#head)
@@ -353,6 +354,23 @@ $collection = collect([['a', 'b'], ['c', 'd'], ['e', 'f']])->fromPairs();
 $collection->toArray(); // returns ['a' => 'b', 'c' => 'd', 'e' => 'f']
 ```
 
+### `getDeeply`
+
+Returns an item from the collection with multidimensional data using "dot" notation.
+Works the same way as native Collection's `pull` method, but without removing an item from the collection.
+
+```php
+$collection = new Collection([
+    'foo' => [
+        'bar' => [
+            'baz' => 100,
+        ]
+    ]
+]);
+
+$collection->getDeeply('foo.bar.baz') // 100
+```
+
 ### `glob`
 
 Returns a collection of a `glob()` result.

src/CollectionMacroServiceProvider.php

@@ -31,6 +31,7 @@ private function macros(): array
             'firstOrPush' => \Spatie\CollectionMacros\Macros\FirstOrPush::class,
             'fourth' => \Spatie\CollectionMacros\Macros\Fourth::class,
             'fromPairs' => \Spatie\CollectionMacros\Macros\FromPairs::class,
+            'getDeeply' => \Spatie\CollectionMacros\Macros\GetDeeply::class,
             'getNth' => \Spatie\CollectionMacros\Macros\GetNth::class,
             'glob' => \Spatie\CollectionMacros\Macros\Glob::class,
             'groupByModel' => \Spatie\CollectionMacros\Macros\GroupByModel::class,

src/Macros/GetDeeply.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Spatie\CollectionMacros\Macros;
+
+use Illuminate\Support\Arr;
+
+/***
+ * Get an item from the collection with multidimensional data using "dot" notation.
+ *
+ * @param mixed $key
+ * @param mixed $default
+ *
+ * @mixin \Illuminate\Support\Collection
+ *
+ * @return mixed
+ */
+class GetDeeply
+{
+    public function __invoke()
+    {
+        return function ($key, $default = null) {
+            return Arr::get($this->items, $key, $default);
+        };
+    }
+}

tests/Macros/GetDeeplyTest.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace Spatie\CollectionMacros\Test\Macros;
+
+use Illuminate\Support\Collection;
+use Spatie\CollectionMacros\Test\TestCase;
+
+class GetDeeplyTest extends TestCase
+{
+    /** @test */
+    public function it_retrieves_item_from_collection()
+    {
+        $collection = new Collection(['foo', 'bar']);
+
+        $this->assertSame(
+            'foo',
+            $collection->getDeeply(0)
+        );
+    }
+
+    /** @test */
+    public function it_retrieves_item_from_collection_using_dot_notation()
+    {
+        $collection = new Collection([
+            'foo' => [
+                'bar' => [
+                    'baz' => 100,
+                ],
+            ],
+        ]);
+
+        $this->assertSame(
+            100,
+            $collection->getDeeply('foo.bar.baz')
+        );
+    }
+
+    /** @test */
+    public function it_doesnt_remove_item_from_collection()
+    {
+        $collection = new Collection(['foo', 'bar']);
+
+        $collection->getDeeply(0);
+
+        $this->assertEquals(
+            [
+                0 => 'foo',
+                1 => 'bar',
+            ],
+            $collection->all()
+        );
+    }
+
+    /** @test */
+    public function it_returns_default()
+    {
+        $collection = new Collection([]);
+
+        $this->assertSame(
+            'foo',
+            $collection->getDeeply(0, 'foo')
+        );
+    }
+}