array_merge
Combines arrays into one, overwriting duplicate string keys and renumbering all integer keys.
array_merge(array ...$arrays): array- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$arraysoptional | array | Any number of arrays to merge, in order. Later arrays win for duplicate string keys. |
Return value
arrayA new array containing the merged elements. Returns an empty array when called with no arguments.
Errors
Throws a TypeError if any argument is not an array.
Changelog
- PHP 7.4.0Can now be called with no arguments at all; previously at least one array was required.
array_merge() appends arrays end to end and returns the result. How a key survives depends entirely on its type, and that split is the whole story of this function.
String keys versus integer keys
String keys are matched across arrays: a later array's value overwrites an earlier one. That makes array_merge($defaults, $options) the standard way to apply overrides to a flat config array.
Integer keys are never matched. Every value under an integer key is appended and the whole result is renumbered from 0. So merging [5 => 'a'] with [5 => 'b'] gives you [0 => 'a', 1 => 'b'], not one element. Numeric strings such as '24' count as integer keys here, because PHP normalises them on insertion.
When to reach for it
Reach for it to concatenate lists, to layer flat option arrays, or to flatten a small set of arrays with array_merge(...$groups). If you need integer keys left alone, use array_replace() or the union operator +. If nested arrays should be merged rather than replaced, use array_merge_recursive() — but read its page first, because its handling of duplicate string keys surprises most people.
For simply appending two lists, the spread form [...$a, ...$b] is equivalent and usually a touch faster, though it rejects arrays with string keys before PHP 8.1.
Example
When to use it
- Layer a user's saved settings on top of a flat array of defaults
- Concatenate paginated result pages into one list before rendering
- Flatten an array of arrays with array_merge(...$groups)
- Append extra validation errors to an existing error list
Frequently asked questions
Why does array_merge reset my array keys?
Because integer keys are treated as positions, not identities: every integer-keyed value is appended and the result is renumbered from 0. Use array_replace() or the + operator if the integer keys carry meaning, such as database IDs.
What is the difference between array_merge and the + operator?
array_merge lets later arrays overwrite duplicate string keys and renumbers integer keys; + keeps all keys as they are and lets the left-hand array win on conflicts. They give opposite results in almost every case with duplicate keys.
Is array_merge or the spread operator faster?
For appending plain lists, [...$a, ...$b] is generally as fast or faster because it avoids a function call. For layering string-keyed option arrays, array_merge is the clearer choice and the difference is negligible.
More examples
Flattening a list of lists
Spreading the outer array turns each group into a separate argument, so one call flattens a single level. The output is a five-element list a, b, c, d, e. Note this only works when $groups is itself a list; a string-keyed outer array fails before PHP 8.1.
<?php
$groups = [['a', 'b'], ['c'], ['d', 'e']];
$flat = array_merge(...$groups);
print_r($flat);
echo count($flat), " items\n";array_merge versus the union operator
array_merge throws the integer keys away and produces a four-element list. The + operator keeps keys 10, 20 and 30, and the left-hand side wins for the duplicate key 20 — the opposite precedence to array_merge.
<?php
$a = [10 => 'ten', 20 => 'twenty'];
$b = [20 => 'TWENTY', 30 => 'thirty'];
echo "array_merge:\n";
print_r(array_merge($a, $b));
echo "union operator:\n";
print_r($a + $b);Merging with no arguments
Since PHP 7.4 both calls return an empty array instead of raising an error. This matters when you spread a variable that might be empty, such as an unfilled list of result pages.
<?php
$pages = [];
var_dump(array_merge(...$pages));
var_dump(array_merge());
Discussion