feat(support): add groupBy to array utils (#1047)

Author: NeoIsRecursive

src/Tempest/Support/src/Arr/ManipulatesArray.php

@@ -555,6 +555,16 @@ public function join(string $glue = ', ', ?string $finalGlue = ' and '): Immutab
         return namespace\join($this->value, $glue, $finalGlue);
     }
 
+    /**
+     * Groups the array by the results of the provided keyExtractor.
+     *
+     * @param Closure(TValue, TKey): array-key $keyExtractor
+     */
+    public function groupBy(Closure $keyExtractor): static
+    {
+        return $this->createOrModify(namespace\group_by($this->value, $keyExtractor));
+    }
+
     /**
      * Flattens the instance to a single-level array, or until the specified `$depth` is reached.
      *

src/Tempest/Support/src/Arr/functions.php

@@ -932,6 +932,51 @@ function flatten(iterable $array, int|float $depth = INF): array
         return $result;
     }
 
+    /**
+     * Returns a copy of the array grouped by the result of the given `$keyExtractor`.
+     * The keys of the resulting array are the values returned by the `$keyExtractor`.
+     *
+     * ### Example
+     * ```php
+     * group_by(
+     * [
+     * ['country' => 'france', 'continent' => 'europe'],
+     * ['country' => 'Sweden', 'continent' => 'europe'],
+     * ['country' => 'USA', 'continent' => 'america']
+     * ],
+     * fn($item) => $item['continent']
+     * );
+     * // [
+     * //     'europe' => [
+     * //         ['country' => 'france', 'continent' => 'europe'],
+     * //         ['country' => 'Sweden', 'continent' => 'europe']
+     * //     ],
+     * //     'america' => [
+     * //         ['country' => 'USA', 'continent' => 'america']
+     * //     ]
+     * // ]
+     * ```
+     *
+     * @template TKey of array-key
+     * @template TValue
+     * @param iterable<TKey,TValue> $array
+     * @param Closure(TValue, TKey): array-key $keyExtracor
+     */
+    function group_by(iterable $array, Closure $keyExtracor): array
+    {
+        $array = to_array($array);
+
+        $result = [];
+
+        foreach ($array as $key => $item) {
+            $key = $keyExtracor($item, $key);
+
+            $result[$key][] = $item;
+        }
+
+        return $result;
+    }
+
     /**
      * Returns a copy of the given array, with each item transformed by the given callback, then flattens it by the specified depth.
      *

src/Tempest/Support/tests/Arr/ManipulatesArrayTest.php

@@ -1739,4 +1739,28 @@ public function test_dot(): void
                 ->equals($array->dot()),
         );
     }
+
+    public function test_group_by(): void
+    {
+        $array = arr([
+            ['brand' => 'brand1', 'model' => 'model1'],
+            ['brand' => 'brand1', 'model' => 'model2'],
+            ['brand' => 'brand2', 'model' => 'model3'],
+            ['brand' => 'brand2', 'model' => 'model4'],
+        ]);
+
+        $this->assertTrue(
+            arr([
+                'brand1' => [
+                    ['brand' => 'brand1', 'model' => 'model1'],
+                    ['brand' => 'brand1', 'model' => 'model2'],
+                ],
+                'brand2' => [
+                    ['brand' => 'brand2', 'model' => 'model3'],
+                    ['brand' => 'brand2', 'model' => 'model4'],
+                ],
+            ])
+                ->equals($array->groupBy(fn ($item) => $item['brand'])),
+        );
+    }
 }

tests/Integration/Support/ArrayMutabilityTest.php

@@ -31,6 +31,7 @@ final class ArrayMutabilityTest extends TestCase
         'dump',
         'dd',
         'tap',
+        'groupBy',
     ];
 
     public function test_immutable_array(): void