Laravel Collection Public API: groupBy

groupBy($groupBy, $preserveKeys = false)

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 to the $preserveKeys parameter. The groupBy returns a new instance of the Collection class.

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

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

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

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

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<?php
2 
3$canisGenus = $genera->get('Canis'):

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

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

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<?php
2 
3$groupedByNameLength = $collection->groupBy(function($item, $key) {
4    return strlen($item['name']);
5});

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

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

#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:

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

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

 1object(Illuminate\Support\Collection)[137]
 2  protected 'items' =>
 3    array (size=2)
 4      30 =>
 5        object(Illuminate\Support\Collection)[135]
 6          protected 'items' =>
 7            array (size=2)
 8              0 => <== Notice that the keys were NOT preserved.
 9                array (size=2)
10                  'name' => string 'Dave' (length=4)
11                  'age'  => int 30
12              1 => <== Notice that the keys were NOT preserved.
13                array (size=2)
14                  'name' => string 'Jim' (length=3)
15                  'age'  => int 30
16      27 =>
17        object(Illuminate\Support\Collection)[136]
18          protected 'items' =>
19            array (size=1)
20              0 => <== Notice that the keys were NOT preserved.
21                array (size=2)
22                  'name' => string 'Sarah' (length=5)
23                  'age'  => int 27

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

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

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

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

∎