How to group an array by key and value in PHP

Grouping an array means turning a flat list of rows into buckets that share a value: orders by customer, labels by type, log lines by day. In PHP the core of it is one line inside a foreach: $groups[$row['key']][] = $row;. This guide starts from that line, builds a reusable group_by() helper, covers array_reduce, Laravel collections and the new PHP 8.4 and 8.5 array functions, and lists the key-type traps that silently merge groups.

Tested with PHP 8.5.7 and illuminate/collections 13.35.0. The plain-PHP examples run on PHP 8.0 and later, except where a section says it needs 8.4 or 8.5. Every output shown below was printed by running the code.

Is there a built-in group-by function in PHP?

No. PHP 8.5 has no array_group_by(). An RFC to add grouping to array_column was declined, and a separate array_group proposal is listed as inactive on the PHP RFC index. A foreach loop is the standard, fastest way, and Laravel's Collection::groupBy() is the usual framework option.

Group by one key with foreach

Here is the classic problem: rows with a text and a label_id, where you want one entry per text with all its labels:

<?php
declare(strict_types=1);

$data = [
    ['text' => 'X', 'label_id' => 'A1,35'],
    ['text' => 'X', 'label_id' => 'A2,34'],
    ['text' => 'Y', 'label_id' => 'B1,29'],
    ['text' => 'Z', 'label_id' => 'C1,20'],
    ['text' => 'Z', 'label_id' => 'C2,19'],
    ['text' => 'Z', 'label_id' => 'C3,18'],
];

// 1. Group with foreach: text => list of label_id values
$labelsByText = [];
foreach ($data as $row) {
    $labelsByText[$row['text']][] = $row['label_id'];
}

// 2. Reshape into one row per group (the original output format)
$output = [];
foreach ($labelsByText as $text => $labels) {
    $output[] = ['text' => $text, 'label_id' => $labels];
}
echo json_encode($output, JSON_PRETTY_PRINT), PHP_EOL;

Output:

[
    {"text": "X", "label_id": ["A1,35", "A2,34"]},
    {"text": "Y", "label_id": ["B1,29"]},
    {"text": "Z", "label_id": ["C1,20", "C2,19", "C3,18"]}
]

$labelsByText[$row['text']][] = ... creates the bucket the first time a key appears and appends after that. PHP arrays keep insertion order, so groups come out in the order their first row appeared. The second loop only reshapes the result; if an associative array such as ['X' => ['A1,35', 'A2,34'], ...] suits your code, stop after the first loop.

A reusable group_by() helper

When you group in more than one place, a small typed function keeps the code clear. It accepts a column name or a callback, and any iterable, including generators:

<?php
declare(strict_types=1);

/**
 * Group rows by a column name or by the result of a callback.
 *
 * @template T of array
 * @param iterable<T> $rows
 * @param string|callable(T): (int|string) $key
 * @return array<int|string, list<T>>
 */
function group_by(iterable $rows, string|callable $key): array
{
    $groups = [];
    foreach ($rows as $row) {
        $groupKey = is_string($key) ? $row[$key] : $key($row);
        $groups[$groupKey][] = $row;
    }
    return $groups;
}

$orders = [
    ['id' => 101, 'customer' => 'acme',   'status' => 'paid',     'total_cents' => 12000, 'placed' => '2026-09-03'],
    ['id' => 102, 'customer' => 'globex', 'status' => 'pending',  'total_cents' => 8050,  'placed' => '2026-09-14'],
    ['id' => 103, 'customer' => 'acme',   'status' => 'paid',     'total_cents' => 4225,  'placed' => '2026-10-01'],
    ['id' => 104, 'customer' => 'acme',   'status' => 'refunded', 'total_cents' => 1500,  'placed' => '2026-10-02'],
];

$byCustomer = group_by($orders, 'customer');                                 // acme => 3 rows, globex => 1
$byMonth = group_by($orders, fn (array $o): string => substr($o['placed'], 0, 7)); // '2026-09', '2026-10'

Group by a callback when the key is computed: a month from a date, a price band, or a lower-cased email domain.

Nested groups and totals

Add another [...] level to group by two keys, or skip storing rows and keep running totals instead, which uses far less memory on big inputs:

// Two levels: customer, then status
$nested = [];
foreach ($orders as $order) {
    $nested[$order['customer']][$order['status']][] = $order['id'];
}
// {"acme":{"paid":[101,103],"refunded":[104]},"globex":{"pending":[102]}}

// Totals per group without keeping the rows
$totals = [];
foreach ($orders as $order) {
    $totals[$order['customer']] ??= ['orders' => 0, 'revenue_cents' => 0];
    $totals[$order['customer']]['orders']++;
    $totals[$order['customer']]['revenue_cents'] += $order['total_cents'];
}
// {"acme":{"orders":3,"revenue_cents":17725},"globex":{"orders":1,"revenue_cents":8050}}

Amounts are in integer cents on purpose: summing floats such as 0.1 + 0.2 gives rounding errors that show up in financial totals.

Keep row ids, and why array_column is not grouping

If the input array is keyed by id, keep that key inside each group so you can still look rows up directly:

$orders = [
    101 => ['customer' => 'acme',   'status' => 'paid'],
    102 => ['customer' => 'globex', 'status' => 'pending'],
    103 => ['customer' => 'acme',   'status' => 'paid'],
];

$byStatus = [];
foreach ($orders as $id => $order) {
    $byStatus[$order['status']][$id] = $order;
}
// array_keys per group: {"paid":[101,103],"pending":[102]}

array_column(array_values($orders), 'status', 'customer');
// {"acme":"paid","globex":"pending"}  (acme's first row was overwritten)

A common mistake is to reach for array_column($rows, 'status', 'customer'). It re-indexes rather than groups: when two rows share the same index key, the later row overwrites the earlier one. That overwrite is exactly what the declined RFC wanted to change.

array_reduce: works, but slow on large arrays

The functional version is often suggested:

$byStatus = array_reduce(
    $orders,
    function (array $groups, array $order): array {
        $groups[$order['status']][] = $order['id'];
        return $groups;
    },
    [],
);
// {"paid":[101,103],"pending":[102],"refunded":[104]}

It returns the right result, but it is much slower. In our benchmark of 200,000 rows into 500 groups on PHP 8.5.7, a foreach took about 14 ms, collect()->groupBy() about 74 ms, and array_reduce about 740 ms. The carry array is passed into the callback by value and modified there while array_reduce still holds a reference, so PHP has to copy the outer array of groups on every iteration. Use it for small arrays if you like the style; use foreach for anything large.

PHP 8.4 and 8.5 helpers that help around grouping

None of the new functions group, but they make working with each group shorter. PHP 8.4 added array_find(), array_find_key(), array_any() and array_all(); PHP 8.5 added array_first(), array_last() and the pipe operator |>:

// PHP 8.5: the pipe operator. Arrow functions must be wrapped in parentheses.
$paidByCustomer = $orders
    |> (fn (array $rows): array => array_filter($rows, fn (array $o): bool => $o['status'] === 'paid'))
    |> (fn (array $rows): array => group_by($rows, 'customer'))
    |> (fn (array $groups): array => array_map(fn (array $g): int => count($g), $groups));
// {"acme":2}

// PHP 8.4 (array_find, array_any) and 8.5 (array_first, array_last) on one group
$acme = $byCustomer['acme'];
array_first($acme)['id'];                                              // 101
array_last($acme)['id'];                                               // 104
array_any($acme, fn (array $o): bool => $o['status'] === 'refunded');  // true
array_find($acme, fn (array $o): bool => $o['total_cents'] > 10000)['id'] ?? null; // 101

See what's new in PHP 8.5 for the rest of the release.

Laravel collections: groupBy, mapToGroups and countBy

In a Laravel application, groupBy() returns a collection of collections, keyed by the group value. It accepts a column, a dot-notation path, a closure, or an array of these for multi-level grouping:

use Illuminate\Support\Collection;

$orders = collect($orders);

// Group, then keep only the ids
$orders->groupBy('customer')->map(fn (Collection $g) => $g->pluck('id'));
// {"acme":[101,103,104],"globex":[102]}

// Two levels at once
$orders->groupBy(['customer', 'status']);

// Keep the original keys inside each group
$orders->keyBy('id')->groupBy('status', preserveKeys: true)->map->keys();
// {"paid":[101,103],"pending":[102],"refunded":[104]}

// Build groups and values in one pass
$orders->mapToGroups(fn (array $o) => [$o['status'] => $o['total_cents']]);
// {"paid":[12000,4225],"pending":[8050],"refunded":[1500]}

// Aggregates per group, and counts only
$orders->groupBy('customer')->map(fn (Collection $g) => [
    'orders' => $g->count(),
    'revenue_cents' => $g->sum('total_cents'),
]);
$orders->countBy('status');   // {"paid":2,"pending":1,"refunded":1}

Note that groupBy() on an Eloquent query and on a collection are different things. The query builder method adds SQL GROUP BY; the collection method groups rows already loaded into PHP:

// In the database: one row per customer, no PHP loop
$totals = DB::table('orders')
    ->select('customer_id')
    ->selectRaw('COUNT(*) AS orders, SUM(total_cents) AS revenue_cents')
    ->groupBy('customer_id')
    ->get();

// In memory: every order is loaded first, then grouped in PHP
$grouped = Order::query()->get()->groupBy('customer_id');

If you only need counts or sums, let the database do the grouping. It avoids loading every row, and with an index on the grouping column it is usually far faster. Teams that find these loops spreading through controllers usually benefit from moving them into query objects or reports; our Laravel and PHP development team does that kind of refactoring.

Key-type traps that merge or break groups

PHP array keys can only be integers or strings, and other values are converted. That causes groups to merge silently, or code to fail at runtime. These are the results we got on PHP 8.5.7:

• Numeric strings become integers. '1', 1 and true all become key 1, so three different values end in one group. '01' stays a string. Casting with (string) does not help, because PHP converts the numeric string back to an integer key; prefix the key (for example 'c' . $id) if the difference matters.
• null keys are deprecated in PHP 8.5. Using null as an offset now raises "Using null as an array offset is deprecated, use an empty string instead". Decide what missing values should group under, for example $row['status'] ?? 'unknown'.
• Floats are truncated. 1.5 becomes 1 with "Implicit conversion from float 1.5 to int loses precision". Round or format the value into a string key.
• Objects and enums cannot be keys. A DateTimeImmutable or an enum case throws TypeError: Cannot access offset of type ... on array. Use $date->format('Y-m-d') or $enum->value for a backed enum.
• Missing columns. $row['missing'] raises "Undefined array key" and then groups under an empty key. Validate input rows first.

When not to group in PHP

• The data comes from SQL and you need counts, sums or the latest row per group: use GROUP BY or window functions instead.
• The input is very large (a multi-gigabyte CSV): grouping in memory holds every row. Stream the file and keep only running totals, or load it into a database table first.
• Order inside each group matters: sort first (for example with usort), then group, because grouping keeps the input order.

Cloudsoft Zone builds and maintains Laravel and PHP applications, including reporting code that moves heavy grouping into well-indexed SQL. See our Laravel and PHP development service.