feat(support): add methods to array helper (#590)

Co-authored-by: Karel Faille <[email protected]>

Author: gturpin-dev

rector.php

@@ -8,7 +8,6 @@
 use Rector\Config\RectorConfig;
 use Rector\DeadCode\Rector\ClassMethod\RemoveUnusedPublicMethodParameterRector;
 use Rector\DeadCode\Rector\PropertyProperty\RemoveNullPropertyInitializationRector;
-use Rector\DeadCode\Rector\Stmt\RemoveUnreachableStatementRector;
 use Rector\Php70\Rector\StaticCall\StaticCallOnNonStaticToInstanceCallRector;
 use Rector\Php74\Rector\Closure\ClosureToArrowFunctionRector;
 use Rector\Php74\Rector\Property\RestoreDefaultNullToNullableTypePropertyRector;

src/Tempest/Support/src/ArrayHelper.php

@@ -48,6 +48,56 @@ public function __construct(
         }
     }
 
+    /**
+     * Get a value from the array and remove it.
+     *
+     * @param array-key $key
+     */
+    public function pull(string|int $key, mixed $default = null): mixed
+    {
+        $value = $this->get($key, $default);
+
+        $this->remove($key);
+
+        return $value;
+    }
+
+    /**
+     * Shuffle the array.
+     *
+     * @return self<TKey, TValue>
+     */
+    public function shuffle(): self
+    {
+        return new self((new Randomizer())->shuffleArray($this->array));
+    }
+
+    /**
+     * @alias of remove.
+     */
+    public function forget(string|int|array $keys): self
+    {
+        return $this->remove($keys);
+    }
+
+    /**
+     * Remove items from the array.
+     *
+     * @param array-key|array<array-key> $keys The keys of the items to remove.
+     *
+     * @return self<TKey, TValue>
+     */
+    public function remove(string|int|array $keys): self
+    {
+        $keys = is_array($keys) ? $keys : [$keys];
+
+        foreach ($keys as $key) {
+            $this->offsetUnset($key);
+        }
+
+        return $this;
+    }
+
     /**
      * Determines if the array is a list.
      *

src/Tempest/Support/tests/ArrayHelperTest.php

@@ -1109,4 +1109,159 @@ public function test_is_assoc(): void
         $this->assertTrue(arr([0 => 'a', 2 => 'b'])->isAssoc());
         $this->assertTrue(arr(['foo' => 'a', 'baz' => 'b'])->isAssoc());
     }
+
+    public function test_remove_with_basic_keys(): void
+    {
+        $collection = arr([1, 2, 3]);
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove(1)
+                ->toArray(),
+            expected: [
+                0 => 1,
+                2 => 3,
+            ],
+        );
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove([0, 2])
+                ->toArray(),
+            expected: [],
+        );
+    }
+
+    public function test_remove_with_associative_keys(): void
+    {
+        $collection = arr([
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'age' => 42,
+        ]);
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove('first_name')
+                ->toArray(),
+            expected: [
+                'last_name' => 'Doe',
+                'age' => 42,
+            ],
+        );
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove(['last_name', 'age'])
+                ->toArray(),
+            expected: [],
+        );
+    }
+
+    public function test_remove_with_no_valid_key(): void
+    {
+        $collection = arr([1, 2, 3]);
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove(42)
+                ->toArray(),
+            expected: [1, 2, 3],
+        );
+
+        $collection = arr([
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'age' => 42,
+        ]);
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove('foo')
+                ->toArray(),
+            expected: [
+                'first_name' => 'John',
+                'last_name' => 'Doe',
+                'age' => 42,
+            ],
+        );
+
+        $this->assertEquals(
+            actual: $collection
+                ->remove(['bar', 'first_name'])
+                ->toArray(),
+            expected: [
+                'last_name' => 'Doe',
+                'age' => 42,
+            ],
+        );
+    }
+
+    public function test_forget_is_alias_of_remove(): void
+    {
+        $first_collection = arr([
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'age' => 42,
+        ])
+            ->remove(42)
+            ->remove('foo')
+            ->remove(['bar', 'first_name']);
+
+        $second_collection = arr([
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'age' => 42,
+        ])
+            ->forget(42)
+            ->forget('foo')
+            ->forget(['bar', 'first_name']);
+
+
+        $this->assertTrue($first_collection->equals($second_collection));
+    }
+
+    public function test_shuffle_actually_shuffles(): void
+    {
+        $array = range('a', 'z');
+
+        $this->assertFalse(
+            arr($array)->shuffle()->toArray() === $array
+            && arr($array)->shuffle()->toArray() === $array,
+        );
+    }
+
+    public function test_shuffle_keeps_same_values(): void
+    {
+        $array = range('a', 'z');
+        $shuffled = arr($array)->shuffle()->toArray();
+        sort($shuffled);
+
+        $this->assertSame(
+            actual  : $shuffled,
+            expected: $array,
+        );
+    }
+
+    public function test_pull(): void
+    {
+        $collection = arr([
+            'first_name' => 'John',
+            'last_name' => 'Doe',
+            'age' => 42,
+        ]);
+
+        $this->assertSame(
+            actual: $collection->pull('first_name'),
+            expected: 'John',
+        );
+
+        $this->assertSame(
+            actual: $collection->toArray(),
+            expected: [
+                'last_name' => 'Doe',
+                'age' => 42,
+            ],
+        );
+    }
 }