array_replace
Replaces values in the first array with values from later arrays that share the same key.
array_replace(array $array, array ...$replacements): array- Added in PHP 5.3.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$array | array | The base array whose elements may be replaced. It is not modified. |
$replacementsoptional | array | Any number of arrays applied left to right; later arrays win for duplicate keys. |
Return value
arrayA new array based on the first argument, with values overwritten by matching keys from the replacement arrays and any new keys appended.
Errors
Throws a TypeError if any argument is not an array.
array_replace() is array_merge() without the integer-key surprise. It walks the replacement arrays in order and, for every key they define, writes that value into a copy of the base array. Keys that do not exist in the base are appended with their original key intact.
Integer keys are keys, not positions
This is the whole reason to prefer it. array_replace([5 => 'a'], [5 => 'b']) gives [5 => 'b'], one element with the key preserved, where array_merge() would produce a two-element list renumbered from zero. If your array is keyed by database ID, product code or line number, array_replace() is the merge you want.
When to reach for it
Layering a flat config over defaults, patching specific indexes of a list, applying a sparse set of overrides to a lookup table, or merging several partial arrays where every key must survive. It is also the correct sibling of the union operator + with the opposite precedence: + lets the left side win, array_replace() lets the right side win.
What trips people up
It is not recursive. A key whose value is an array is overwritten wholesale, not merged into — a nested override of one setting wipes out its siblings. Use array_replace_recursive() for nested structures. Also note that a key set to null in a replacement array still replaces: it writes null rather than being skipped.
Example
When to use it
- Apply user settings on top of a flat defaults array without losing IDs
- Patch specific indexes of a list while leaving the rest untouched
- Merge sparse per-row overrides into an ID-keyed lookup table
- Combine query-string defaults with request parameters
Frequently asked questions
What is the difference between array_replace and array_merge?
array_replace matches integer keys and preserves them, while array_merge treats integer keys as positions, appends the values and renumbers from zero. String-key behaviour is the same in both: the last array wins.
Is array_replace recursive?
No. A key whose value is an array is replaced entirely, so nested sibling keys are lost. Use array_replace_recursive() to merge nested structures.
What is the difference between array_replace and the + operator?
Both preserve keys, but the precedence is opposite: with + the left-hand array wins for duplicate keys, while with array_replace the rightmost array wins. array_replace also accepts any number of arrays in one call.
More examples
array_replace versus array_merge
array_replace keeps keys 7 and 12 and updates only the second value. array_merge renumbers everything, producing a three-element list 0, 1, 2 with both the old and the new gadget — the ID association is destroyed.
<?php
$byId = [7 => 'widget', 12 => 'gadget'];
$patch = [12 => 'GADGET'];
echo "array_replace:\n";
print_r(array_replace($byId, $patch));
echo "array_merge:\n";
print_r(array_merge($byId, $patch));Layering several override arrays
Arrays are applied left to right, so the user's values beat the team's and both beat the system defaults. The output shows theme dark from the team layer and lang pt from the user layer.
<?php
$system = ['theme' => 'light', 'lang' => 'en', 'tz' => 'UTC'];
$team = ['theme' => 'dark'];
$user = ['tz' => 'Europe/Lisbon', 'lang' => 'pt'];
$final = array_replace($system, $team, $user);
print_r($final);
echo $final['theme'], ' / ', $final['lang'], "\n";Nested values are replaced whole
array_replace drops the host key entirely because the whole 'db' array is overwritten by the one-key override. array_replace_recursive descends into it and keeps host while updating port — that is the version you usually want for config.
<?php
$defaults = ['db' => ['host' => 'localhost', 'port' => 3306]];
$override = ['db' => ['port' => 3307]];
print_r(array_replace($defaults, $override));
print_r(array_replace_recursive($defaults, $override));
Discussion