Grouping Laravel Collections with GroupBy

When PHP code has loaded records into a Laravel Collection, an object that holds a set of items, groupBy organizes those records into smaller collections using a field in each record or a value the code calculates. Laravel uses a group key, a label for a value, to put items with the same value together. The method returns another collection, which you can loop over or search for a particular group.

Laravel's query builder also has a groupBy method for grouping rows in a database query. This article covers the Collection method and uses the Laravel 12.x API. Pass a field name to group by an existing value, a callback (a function Laravel runs for each item) to calculate a key, or an array of criteria to create nested groups.

Group items by one field

Pass the field name to group records by its value:

$grouped = $products->groupBy('account_id');

Laravel creates one group for each different account_id value. Products with the same account ID go in the same group, and each group contains the original products. The Laravel Collections documentation also shows how to use a callback when you need to calculate the grouping value.

A callback can group items by part of an account ID:

$grouped = $products->groupBy(
    fn (array $item, int $key) => substr($item['account_id'], -3)
);

Pass a field name to group items by its existing value. Use a callback when you need to change a value or calculate a key from the item. Laravel passes the callback the item and its original key. Include only the parameters your calculation uses.

Group by multiple criteria

Pass an array of criteria, or grouping rules, to create groups inside groups. Laravel applies each entry in order, adding one level for each:

$grouped = $items->groupBy(
    ['skill', fn (array $item) => $item['roles']],
    preserveKeys: true
);

Laravel groups items first by skill, then by the roles the callback returns. The outer group keys are skills, and the keys inside each outer group are roles. The final groups contain the matching items.

A criterion that returns multiple values, such as an array of roles, places an item in each corresponding subgroup. As a result, one item can appear in more than one role group. Laravel documents this nested behavior in its multiple-criteria example.

Laravel creates a new group level for each criterion in the array. To group by multiple fields under one key, return a combined value from a single callback:

$grouped = $items->groupBy(
    fn (array $item) => $item['skill'] . ':' . $item['role']
);

Choose a separator that cannot be confused with the values you combine, or use another encoding that keeps each combination distinct.

Read nested groups and preserve item keys

Grouping by multiple criteria creates nested collections. Get the outer group first, then retrieve the role subgroup from that collection:

$skillGroup = $grouped->get(1);
$roleGroup = $skillGroup?->get('Role_1');

The null-safe operator ?-> returns null instead of calling get on a missing outer group. When iterating, use nested loops so each loop handles one grouping level:

foreach ($grouped as $skill => $roleGroups) {
    foreach ($roleGroups as $role => $itemsInGroup) {
        // Work with the items in this skill and role group.
    }
}

The preserveKeys: true argument keeps each item's original key, its key in the collection before grouping, inside the final groups. It preserves the keys of the grouped items, not the skill or role labels. Use it when the original keys carry meaning or later code relies on them.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com