April 22, 2018 —John Koster
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.
1public function groupBy(2 $groupBy,3 $preserveKeys = false4);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 array10 '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 array24 0 =>25 array26 'genus' => string 'Cucumis'27 'species' => string 'C. sativus'28 'subspecies' => null29 '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 array12 '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 array10 'genus' => string 'Canis'11 'species' => string 'C. lupus'12 'subspecies' => string 'C. l. albus'13 'name' => string 'tundra wolf'14 1 =>15 array16 '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 array24 0 =>25 array26 'genus' => string 'Cucumis'27 'species' => string 'C. sativus'28 'subspecies' => null29 'name' => string 'cucumber'groupByBy 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 were10 NOT preserved.11 array12 'name' => string 'Dave'13 'age' => int 3014 1 =>15 ^== Notice that the keys were16 NOT preserved.17 array18 'name' => string 'Jim'19 'age' => int 3020 27 =>21 object(Illuminate\Support\Collection)22 protected 'items' =>23 array24 0 =>25 ^== Notice that the keys were26 NOT preserved.27 array28 'name' => string 'Sarah'29 'age' => int 27The 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 array11 'name' => string 'Dave'12 'age' => int 3013 'second' =>14 ^== Notice that keys WERE preserved.15 array16 'name' => string 'Jim'17 'age' => int 3018 27 =>19 object(Illuminate\Support\Collection)20 protected 'items' =>21 array22 'third' =>23 ^== Notice that keys WERE preserved.24 array25 'name' => string 'Sarah'26 'age' => int 27∎