[12.x] Added Arr::groupBy() helper function for array grouping

[vishal2931]

Overview

This PR introduces a new Arr::groupBy() helper method to the Illuminate\Support\Arr class. It provides a convenient way to group associative array by a specified key or a callback, with optional support for preserving the original array keys.

Example

use Illuminate\Support\Arr;

$products = [
    [
        'id' => 1,
        'type' => 'Electronics',
        'name' => 'Laptop',
    ],
    [
        'id' => 2,
        'type' => 'Clothing',
        'name' => 'T-shirt',
    ],
    [
        'id' => 3,
        'type' => 'Electronics',
        'name' => 'Smartphone',
    ],
];

// Group by type
$grouped = Arr::groupBy($products, 'type');

/*
Output: 
[
    'Electronics' => [
        [
            'id' => 1,
            'type' => 'Electronics',
            'name' => 'Laptop',
        ],
        [
            'id' => 3,
            'type' => 'Electronics',
            'name' => 'Smartphone',
        ],
    ],
    'Clothing' => [
        [
            'id' => 2,
            'type' => 'Clothing',
            'name' => 'T-shirt',
        ],
    ],
]
*/

// With preserved keys
$grouped = Arr::groupBy($products, 'type', true);

/*
Output: 
[
    'Electronics' => [
        0 => [
            'id' => 1,
            'type' => 'Electronics',
            'name' => 'Laptop',
        ],
        2 => [
            'id' => 3,
            'type' => 'Electronics',
            'name' => 'Smartphone',
        ],
    ],
    'Clothing' => [
        1 => [
            'id' => 2,
            'type' => 'Clothing',
            'name' => 'T-shirt',
        ],
    ],
]
*/

// With callback
$grouped = Arr::groupBy($products, function ($item) {
    return strtolower($item['type']);
});

/*
Output:
[
    'electronics' => [
        [
            'id' => 1,
            'type' => 'Electronics',
            'name' => 'Laptop',
        ],
        [
            'id' => 3,
            'type' => 'Electronics',
            'name' => 'Smartphone',
        ],
    ],
    'clothing' => [
        [
            'id' => 2,
            'type' => 'Clothing',
            'name' => 'T-shirt',
        ],
    ],
]
*/

[shaedrich]

By doing this, we would end up having groupBy() on Arr while having mapToGroups() on Collection—not sure if we want to different approaches 🤔

[rodrigopedra]

@shaedrich, collections also have a groupBy method, with a similar implementation.

https://laravel.com/docs/12.x/collections#method-groupby

My guess is that @vishal2931 took inspiration from that implementation.

[shaedrich]

Ah, thanks for the hint—nevermind 🤦🏻

[rodrigopedra]

I would ensure $groupBy is a callback out the loop, so we don't need to check if it is a callback on every item.

Something like this:

$groupBy = is_callable($groupBy) ? $groupBy : fn ($item) => static::get($item, $groupBy);

foreach ($array as $key => $item) {
    $groupKey = $groupBy($item, $key);

    // ...
}

[vishal2931]

Thanks for the feedback, but that approach looks more readable than this one. 🤔

[vishal2931]

@shaedrich, collections also have a groupBy method, with a similar implementation.

https://laravel.com/docs/12.x/collections#method-groupby

My guess is that @vishal2931 took inspiration from that implementation.

@rodrigopedra Correct. It will work same as Collection groupBy.

[vishal2931]

By doing this, we would end up having groupBy() on Arr while having mapToGroups() on Collection—not sure if we want to different approaches 🤔

Yes you're right. I was thinking that instead of transforming it into a collection and then back to an array, we can do it directly on the array. What do you think? 🤔

[taylorotwell]

Thanks for your pull request to Laravel!

Unfortunately, I'm going to delay merging this code for now. To preserve our ability to adequately maintain the framework, we need to be very careful regarding the amount of code we include.

If applicable, please consider releasing your code as a package so that the community can still take advantage of your contributions!