PHP array_replace_recursive() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Array

Definition

In PHP, array_replace_recursive() replaces values of the first array with values from other arrays, going deep into nested arrays.

It is a common way to apply custom settings on top of nested default settings without losing the keys you did not change.

Syntax

Call array_replace_recursive() with the values you need. Start with this line.

PHP
$config = array_replace_recursive($defaults, $custom);
CallWhat it does
array_replace_recursive($defaults, $custom)Overrides only the nested keys that exist in $custom.
array_replace_recursive(["a" => [1, 2, 3]], ["a" => [1 => "B"]])Returns ["a" => [1, "B", 3]].
array_replace_recursive($a, $b, $c)Applies each replacement array in order.

When both values are arrays, they are merged by key. If one of them is not an array, the replacement value simply wins.

Library declarations
PHP
array_replace_recursive(array $array, array ...$replacements): array

Parameters

ParameterDescription
arrayRequired. The base array.
replacementsOptional. One or more arrays whose values replace or add to the base array, at every level.

Return Value

Return ValueDescription
arrayA new array with all replacements applied at every depth.

PHP Examples

Example 1 — Override Nested Settings

Change only the database port and the debug flag.

PHP
<?php
$defaults = ["db" => ["host" => "localhost", "port" => 3306], "debug" => false];
$custom   = ["db" => ["port" => 3307], "debug" => true];

$config = array_replace_recursive($defaults, $custom);

echo json_encode($config), PHP_EOL;

How It Works

  1. Create the defaults. The db setting has a host and a port.
  2. Create the custom settings. They only change port and debug.
  3. Call array_replace_recursive(). The nested db arrays are merged by key.
  4. Read the result. The host is kept and the port is changed.

Example 2 — Compare With array_replace()

array_replace() works only on the top level, so it loses the nested host.

PHP
<?php
$defaults = ["db" => ["host" => "localhost", "port" => 3306], "debug" => false];
$custom   = ["db" => ["port" => 3307], "debug" => true];

echo json_encode(array_replace($defaults, $custom)), PHP_EOL;
echo json_encode(array_replace_recursive($defaults, $custom)), PHP_EOL;

How It Works

  1. Use the same data. Both functions get the defaults and custom settings.
  2. Run array_replace(). The whole db array is swapped, so host is lost.
  3. Run array_replace_recursive(). It goes inside db and keeps host.
  4. Pick the right one. Use the recursive version for nested configuration.

Example 3 — Scalars, Lists and Type Changes

See what happens when the replacement is not an array, or a list is only partly replaced.

PHP
<?php
echo json_encode(array_replace_recursive(["a" => [1, 2]], ["a" => "x"])), PHP_EOL;
echo json_encode(array_replace_recursive(["a" => [1, 2, 3]], ["a" => [1 => "B"]])), PHP_EOL;

How It Works

  1. Replace an array with a string. The replacement is not an array, so it simply wins.
  2. Read the first result. Key a becomes "x".
  3. Replace one list item. Only index 1 is given, so only it is replaced.
  4. Read the second result. The values 1 and 3 are kept.

Frequently Asked Questions

It replaces values of the first array with values from other arrays, going into nested arrays so only matching keys change.
array_replace() replaces whole nested arrays. array_replace_recursive() merges nested arrays key by key.
array_merge_recursive() collects duplicate values into arrays. array_replace_recursive() overwrites them.
No. It returns a new array and leaves the originals as they were.
If either the old or new value is not an array, the replacement value is used as it is.

Next: array_reverse()

array_reverse() returns a new array with the items in the opposite order.

array_reverse() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful