PHP Function: array_replace_recursive()

The array_replace_recursive() function in PHP merges arrays while keeping the structure and keys of the original arrays intact. It replaces elements in the first array with elements from subsequent arrays, descending into nested arrays as it goes. This makes it the right tool when you need to overlay one multidimensional array on top of another — for example, applying user overrides on top of default configuration without flattening the nested data.

This chapter covers the function's syntax, how the recursion actually behaves, several worked examples (including multiple replacement arrays), and how it differs from related functions like array_replace() and array_merge_recursive().

Syntax

The syntax of the array_replace_recursive() function is straightforward, with the first argument being the array that will be modified and subsequent arguments being arrays from which elements will be merged into the first array.

PHP array_replace_recursive function syntax

array_replace_recursive(array $array, array ...$replacements): array

The first argument is the base array. Every following array is applied on top of it, left to right, so a value in a later array wins over the same key in an earlier one. The function returns a new array and does not modify the arguments in place.

How it Works

The array_replace_recursive() function works by iterating over all elements of the arrays passed as arguments. For each element, the function will check if the key exists in the first array. If the key does not exist, the element will simply be added to the first array. If the key does exist, the function will check if the value is an array. If it is, the function will recursively call itself with the current value in the first array and the corresponding value in the second array as the arguments. If the value is not an array, it will simply be replaced with the value from the second array.

This process is repeated for all subsequent arrays passed as arguments, with elements being added or replaced in the first array as necessary. The final result is a single array that is the result of merging all elements from the input arrays. Note: Unlike array_merge_recursive(), this function replaces numeric keys instead of merging them by index.

Examples

Here are a few examples of how the array_replace_recursive() function can be used in practice:

PHP example of array_replace_recursive function usage

The output of this code will be:

Array
(
    [a] => Array
        (
            [b] => d
        )
)

The recursion kicks in because both $array1['a'] and $array2['a'] are arrays, so the function descends into them and replaces b rather than overwriting the whole a branch.

Another example:

PHP Another example of array_replace_recursive function usage

The output of this code will be:

Array
(
    [a] => d
)

Here the recursion does not happen: $array2['a'] is the scalar string 'd', not an array. When the replacement value is not an array, the entire existing value (including any nested array) is overwritten outright. The function only recurses when the value exists as an array on both sides.

Merging multiple arrays and adding new keys

You can pass any number of replacement arrays. They are applied in order, and keys that do not yet exist are added rather than replaced.

PHP array_replace_recursive with multiple arrays

<?php

$defaults = ['db' => ['host' => 'localhost', 'port' => 3306]];
$env      = ['db' => ['host' => 'db.internal']];
$cli      = ['db' => ['port' => 5432], 'debug' => true];

$result = array_replace_recursive($defaults, $env, $cli);

print_r($result);

?>

The output of this code will be:

Array
(
    [db] => Array
        (
            [host] => db.internal
            [port] => 5432
        )

    [debug] => 1
)

The nested host and port keys are each overridden by the later arrays, while the brand-new debug key is appended. This left-to-right overlay is exactly why the function is so handy for layering configuration.

array_replace_recursive() vs. related functions

• array_replace() does the same overlay but only at the top level — it never descends into nested arrays, so a nested value is always replaced wholesale.
• array_merge_recursive() combines values that share a key (turning two scalars into an array of both) instead of replacing them, and it renumbers integer keys. array_replace_recursive() keeps a single replacing value and preserves the original keys.
• array_merge() is the non-recursive merge that also renumbers integer keys.

If your goal is "take these defaults and override them with these values," reach for array_replace_recursive(). If your goal is "collect everything under each key," reach for array_merge_recursive().

Conclusion

In conclusion, the array_replace_recursive() function in PHP provides a convenient way to merge arrays while preserving their original structure and keys. It is particularly valuable for updating nested configuration data or merging structured datasets without manual iteration.

Practice