PHP array_replace_recursive() Function: Usage and Examples

When writing PHP applications, you may need to replace values within nested configuration arrays while retaining untouched keys. This is useful in everyday tasks such as working with imported data, application settings, user-facing lists, and reports.

The array_replace_recursive() operation provides this behavior directly. The examples below show what happens to the inputs and what to check before using the result in your application.

What Is array_replace_recursive() in PHP?

Replace values within nested configuration arrays while retaining untouched keys.

Its syntax is:

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

Parameters used by this operation:

• $array — The collection being examined or updated.
• $replacements — The value supplied for this argument affects the operation.

If both matching values are arrays PHP descends recursively; a scalar replacement replaces the existing value. This is not a general data validation tool.

Example 1: Basic Usage

Start with a small, self-contained input so you can inspect exactly how the operation behaves.

<?php

$defaults = ["mail" => ["host" => "localhost", "port" => 25], "debug" => false];
$override = ["mail" => ["port" => 587]];
print_r(array_replace_recursive($defaults, $override));

Output:

Array
(
    [mail] => Array
        (
            [host] => localhost
            [port] => 587
        )

    [debug] => 
)

The output shows the result of the first call. Check the printed keys and values as well as their order.

Example 2: Another Important Case

This variation highlights another input shape, a comparison option, or a change in the collection.

<?php

$original = ["features" => ["search" => true, "chat" => false]];
$changes = ["features" => ["chat" => true]];
print_r(array_replace_recursive($original, $changes));

Output:

Array
(
    [features] => Array
        (
            [search] => 1
            [chat] => 1
        )

)

Compare this result with Example 1: the difference comes from the input or option selected, not from additional processing.

Practical Example: Merge validated application settings without discarding unrelated nested defaults

Merge validated application settings without discarding unrelated nested defaults. Save the code in a PHP file and adapt the sample data to your project.

<?php

$defaults = ["display" => ["theme" => "light", "pageSize" => 15], "security" => ["timeout" => 30]];
$userOptions = ["display" => ["pageSize" => 25]];
$settings = array_replace_recursive($defaults, $userOptions);
echo "Theme: " . $settings["display"]["theme"] . PHP_EOL;
echo "Page size: " . $settings["display"]["pageSize"] . PHP_EOL;

Output:

Theme: light
Page size: 25

The output comes from the completed workflow shown above. When adapting it, change the source records and keep the same checks for missing, unexpected, or invalid values.

Important Behavior and Edge Cases

If both matching values are arrays PHP descends recursively; a scalar replacement replaces the existing value. This is not a general data validation tool.

• Test the operation with empty or missing input and decide how your application should respond.
• Read the return value independently from any changes to variables passed by reference.
• Validate untrusted input before using the result for permissions, database changes, or user-visible output.

Comparison With Related Functions

Common Beginner Mistakes

Key Takeaways

• array_replace_recursive() helps you replace values within nested configuration arrays while retaining untouched keys.
• If both matching values are arrays PHP descends recursively; a scalar replacement replaces the existing value. This is not a general data validation tool.
• array_replace() replaces a nested array as a whole; array_merge_recursive() combines colliding values into arrays.
• Use the practical example as a starting point, but validate real application inputs.

array_replace_recursive() is useful when you need to replace values within nested configuration arrays while retaining untouched keys. Use its documented rules and the examples above to choose the right behavior for your data.