Collection::combine
Uses the collection's values as keys and the given values as values, producing an associative collection.
combine(iterable|Arrayable $values): Collection- Added in Laravel 5.1
Parameters
| Parameter | Type | Description |
|---|---|---|
$$values | \Illuminate\Contracts\Support\Arrayable<array-key, TCombineValue>|iterable<array-key, TCombineValue> | The values to pair with this collection's items. Must contain exactly as many items as the collection. |
Return value
Collection<TValue, TCombineValue>A new collection whose keys are this collection's values and whose values come from the argument.
Errors
ValueError when the two sets do not contain the same number of items, and TypeError if a value used as a key is not a valid array key.
combine() is array_combine() with a fluent face. The current collection supplies the keys; the argument supplies the values. Getting the direction backwards is the most common mistake — collect($keys)->combine($values), never the other way round.
When to reach for it
Any time you hold two parallel lists that belong together: a CSV header row and a data row, column names and a row of results, a list of locale codes and their translated labels. Mapping combine() over every data row is the standard way to turn a headerless CSV into records.
Counts must match exactly
PHP throws a ValueError — not a warning, not a truncated result — when the two sets differ in length. That makes it unsafe on user-supplied data. Compare count() first, or pad the shorter side, before combining rows parsed from an uploaded file where one line may have a trailing comma.
Keys must be valid
Only strings and integers can be array keys. Floats are truncated to integers, booleans become 0 and 1, and null becomes an empty string. Duplicate values in the key collection collapse into one entry, so ['a','a'] combined with [1,2] yields a single 'a' => 2.
Example
When to use it
- Turn a CSV header row plus each data row into associative records.
- Pair a list of column names with a row returned from a raw query.
- Build a select-box options array from parallel value and label lists.
Frequently asked questions
Which side of combine() supplies the keys?
The collection you call it on supplies the keys, and the argument supplies the values — collect(['name','age'])->combine(['George', 29]) gives ['name' => 'George', 'age' => 29].
Why does combine() throw a ValueError?
Because the collection and the argument hold different numbers of items, which array_combine() rejects outright. Compare the counts first, or pad the shorter side with pad() before combining.
What happens if the key collection contains duplicates?
Later pairs overwrite earlier ones, so the result has fewer entries than the input — combining ['a','a'] with [1,2] yields a single 'a' => 2.
More examples
Guarding against a ragged CSV
Row two has only two fields. Without the pad()/take() pair, combine() would throw a ValueError and abort the whole import. Normalising each row to the header count turns the missing field into an explicit null the rest of the code can check.
<?php
$lines = collect([
'id,name,email',
'1,Ada,[email protected]',
'2,Finn', // short row — one field missing
]);
$headers = collect(str_getcsv($lines->shift()));
$records = $lines->map(function (string $line) use ($headers) {
$fields = collect(str_getcsv($line));
// Pad or trim so combine() cannot throw on a ragged file.
$fields = $fields->pad($headers->count(), null)
->take($headers->count());
return $headers->combine($fields);
});
print_r($records->toArray());
// [ ['id'=>'1','name'=>'Ada','email'=>'[email protected]'],
// ['id'=>'2','name'=>'Finn','email'=>null] ]Labelling a raw query result
The positional rows become self-describing records, so the formatting loop reads by name instead of by index. Adding a column later means editing the $columns list once rather than renumbering every offset in the loop.
<?php
$columns = collect(['month', 'orders', 'revenue_cents']);
$rows = collect([
['2026-01', 412, 5_120_000],
['2026-02', 388, 4_890_000],
]);
$report = $rows->map(fn (array $r) => $columns->combine($r));
foreach ($report as $line) {
printf(
"%s %4d orders %s\n",
$line['month'],
$line['orders'],
number_format($line['revenue_cents'] / 100, 2)
);
}
// 2026-01 412 orders 51,200.00
// 2026-02 388 orders 48,900.00
Discussion