Laravel 5 Collections: Grouping Collection Elements With groupBy

The groupBy method is used to group a collection based on a given value, represented by the $groupBy parameter. An argument passed to $groupBy can be a simple string, representing the value that the collection should be grouped by, or a callback that returns the value the collection should be grouped by. By default, the groupBy method does not preserve the keys of the collection when grouping, but that can be changed by passing true as the argument to the $preserveKeys parameter. The groupBy returns a new instance of the Collection class.

#Signature

1public function groupBy(
2    $groupBy,
3    $preserveKeys = false
4);

#Example Use

The following collection will be used throughout this section when demonstrating the groupBy method:

 1use Illuminate\Support\Collection;
 2 
 3// Create a new collection instance.
 4$collection = new Collection([
 5    [
 6        'genus'      => 'Canis',
 7        'species'    => 'C. lupus',
 8        'subspecies' => 'C. l. albus',
 9        'name'       => 'tundra wolf'
10    ],
11    [
12        'genus'      => 'Canis',
13        'species'    => 'C. lupus',
14        'subspecies' => 'C. l. arctos',
15        'name'       => 'arctic wolf'
16    ],
17    [
18        'genus'      => 'Cucumis',
19        'species'    => 'C. sativus',
20        'subspecies' => null,
21        'name'       => 'cucumber'
22    ]
23]);

The collection be grouped by the genus of each item like so:

1$genera = $collection->groupBy('genus');

The $genera variable will now be an instance of Collection, and will contain numerous items, each an instance of Collection. The above $genera variable will now have a value similar to the following output:

 1object(Illuminate\Support\Collection)
 2  protected 'items' =>
 3    array
 4      'Canis' =>
 5        object(Illuminate\Support\Collection)
 6          protected 'items' =>
 7            array
 8              0 =>
 9                array
10                  'genus'      => string 'Canis'
11                  'species'    => string 'C. lupus'
12                  'subspecies' => string 'C. l. albus'
13                  'name'       => string 'tundra wolf'
14              1 =>
15                array (size=4)
16                  'genus'      => string 'Canis'
17                  'species'    => string 'C. lupus'
18                  'subspecies' => string 'C. l. arctos'
19                  'name'       => string 'arctic wolf'
20      'Cucumis' =>
21        object(Illuminate\Support\Collection)
22          protected 'items' =>
23            array
24              0 =>
25                array
26                  'genus'      => string 'Cucumis'
27                  'species'    => string 'C. sativus'
28                  'subspecies' => null
29                  'name'       => string 'cucumber'

The original collection was split into two new collections: Cucumis and Canis. Each item that was grouped into the Canis collection can be retrieve like so:

1$canisGenus = $genera->get('Canis'):

The $canisGenus variable would now contain a value similar to the following output:

 1object(Illuminate\Support\Collection)
 2  protected 'items' =>
 3    array
 4      0 =>
 5        array
 6          'genus'      => string 'Canis'
 7          'species'    => string 'C. lupus'
 8          'subspecies' => string 'C. l. albus'
 9          'name'       => string 'tundra wolf'
10      1 =>
11        array
12          'genus'      => string 'Canis'
13          'species'    => string 'C. lupus'
14          'subspecies' => string 'C. l. arctos'
15          'name'       => string 'arctic wolf'

A callback can also be supplied for the $groupBy parameter. The callback should accept an $item and a $key argument, and should also return the criteria that the collection should be grouped by. The following code example will group the original collection based on the length of each items name:

1$groupedByNameLength = $collection->groupBy(
2    function($item, $key) {
3        return strlen($item['name']);
4    }
5);

The $groupedByNameLength variable would be an instance of Collection and contain a value similar to the following output:

 1object(Illuminate\Support\Collection)
 2  protected 'items' =>
 3    array
 4      11 =>
 5        object(Illuminate\Support\Collection)
 6          protected 'items' =>
 7            array
 8              0 =>
 9                array
10                  'genus'      => string 'Canis'
11                  'species'    => string 'C. lupus'
12                  'subspecies' => string 'C. l. albus'
13                  'name'       => string 'tundra wolf'
14              1 =>
15                array
16                  'genus'      => string 'Canis'
17                  'species'    => string 'C. lupus'
18                  'subspecies' => string 'C. l. arctos'
19                  'name'       => string 'arctic wolf'
20      8 =>
21        object(Illuminate\Support\Collection)
22          protected 'items' =>
23            array
24              0 =>
25                array
26                  'genus'      => string 'Cucumis'
27                  'species'    => string 'C. sativus'
28                  'subspecies' => null
29                  'name'       => string 'cucumber'

#Preserving Keys With groupBy

By default, the groupBy method will not preserve the keys in the underlying collection when grouping items. The following code sample shows how the groupBy method groups by default, and the output:

 1use Illuminate\Support\Collection;
 2 
 3 
 4// Create a new collection instance.
 5$collection = new Collection([
 6    'first'  => ['name' => 'Dave',  'age' => 30],
 7    'second' => ['name' => 'Jim',   'age' => 30],
 8    'third'  => ['name' => 'Sarah', 'age' => 27]
 9]);
10 
11$grouped = $collection->groupBy('age');

The $grouped variable would now have a value similar to the following output:

 1object(Illuminate\Support\Collection)
 2    items' =>
 3        array
 4          30 =>
 5            object(Illuminate\Support\Collection)
 6              protected 'items' =>
 7                array
 8                  0 =>
 9                     ^== Notice that the keys were
10                         NOT preserved.
11                    array
12                      'name' => string 'Dave'
13                      'age'  => int 30
14                  1 =>
15                     ^== Notice that the keys were
16                         NOT preserved.
17                    array
18                      'name' => string 'Jim'
19                      'age'  => int 30
20          27 =>
21            object(Illuminate\Support\Collection)
22              protected 'items' =>
23                array
24                  0 =>
25                     ^== Notice that the keys were
26                         NOT preserved.
27                    array
28                      'name' => string 'Sarah'
29                      'age'  => int 27

The groupBy method can be instructed to preserve keys by passing true for the $preserveKeys parameter:

1// Group the collection while preserving keys.
2$grouped = $collection->groupBy('age', true);

The $grouped variable would now contain a value similar to the following output:

 1object(Illuminate\Support\Collection)
 2    'items' =>
 3        array
 4          30 =>
 5            object(Illuminate\Support\Collection)
 6              protected 'items' =>
 7                array
 8                  'first' =>
 9                    ^== Notice that keys WERE preserved.
10                    array
11                      'name' => string 'Dave'
12                      'age'  => int 30
13                  'second' =>
14                    ^== Notice that keys WERE preserved.
15                    array
16                      'name' => string 'Jim'
17                      'age'  => int 30
18          27 =>
19            object(Illuminate\Support\Collection)
20              protected 'items' =>
21                array
22                  'third' =>
23                    ^== Notice that keys WERE preserved.
24                    array
25                      'name' => string 'Sarah'
26                      'age'  => int 27

∎