PHP Array Replace: A Complete Guide

In PHP, the array_replace() function replaces the values of a base array with values from one or more replacement arrays, matching by key. For every key that exists in a later array, that value overwrites the value in the base array; keys that do not yet exist are appended. The original arrays are never modified — array_replace() returns a new array.

This page covers the syntax and parameters of array_replace(), how it handles string vs. numeric keys, how it differs from array_merge(), and the gotcha that it is not recursive (use array_replace_recursive() when you need to merge nested arrays).

When to use it

Reach for array_replace() when you want to override defaults: define a base array of default values, then pass user-supplied overrides as the second argument. Because matching is by key (not by position), it's the cleanest way to merge configuration arrays where keys carry meaning.

Syntax

The syntax for the array_replace function is as follows:

PHP array_replace function syntax

array_replace ( array $array1 , array $array2 [, array $... ] ) : array

array_replace() takes at least one array and accepts any number of additional arrays. It walks through the replacement arrays left to right: each value whose key already exists in $array1 overwrites it, and each new key is appended. Later arrays win over earlier ones. The function returns the resulting array and leaves all inputs untouched.

Note: numeric keys are matched the same way as string keys — by the literal key value, not by position. This is the key difference from array_merge(), which renumbers integer keys.

Parameters

• array1: This is the initial array that will be replaced by the values from the other arrays.
• array2: This is the array whose values will replace the values in array1.
• ...: These are optional additional arrays, whose values will be used to further replace the values in array1.

Examples

Let's consider some examples to see how array_replace works.

Example 1: Replacing Values in a Single Array

PHP Example 1: Replacing Values in a Single Array using array_replace

Output:

Array
(
    [a] => peach
    [b] => banana
    [c] => cherry
)

Here key a exists in both arrays, so $array2 overwrites it (apple → peach). Key b exists only in $array1, so it stays as banana. Key c exists only in $array2, so it is appended to the result.

Example 2: Replacing Values in Multiple Arrays

PHP Example 2: Replacing Values in Multiple Arrays using array_replace

Output:

Array
(
    [a] => peach
    [b] => blueberry
    [c] => cherry
    [d] => date
)

The replacement arrays are applied left to right. Key a is set to peach by $array2. Key b starts as banana but is overwritten by $array3 to blueberry — the last array wins. Keys c (from $array2) and d (from $array3) are new, so they are appended.

Example 3: Not recursive — use array_replace_recursive()

array_replace() replaces whole values, so a nested array on a matching key is replaced entirely rather than merged. When you need a deep merge, use array_replace_recursive().

PHP Example 3: array_replace vs array_replace_recursive

<?php

$base     = ["db" => ["host" => "localhost", "port" => 3306]];
$override = ["db" => ["host" => "example.com"]];

// array_replace overwrites the whole "db" sub-array
print_r(array_replace($base, $override));

// array_replace_recursive merges the nested arrays
print_r(array_replace_recursive($base, $override));

?>

Output:

Array
(
    [db] => Array
        (
            [host] => example.com
        )

)
Array
(
    [db] => Array
        (
            [host] => example.com
            [port] => 3306
        )

)

With array_replace() the original port is lost because the entire db array is replaced. array_replace_recursive() descends into the nested array and keeps port.

array_replace() vs array_merge()

Both combine arrays, but they treat keys differently:

• String keys: behave the same — later values overwrite earlier ones.
• Integer keys: array_merge() renumbers them sequentially, so values are appended rather than overwritten. array_replace() keeps the integer keys and overwrites matching ones.

<?php

$a = [0 => "zero", 1 => "one"];
$b = [1 => "ONE", 2 => "two"];

print_r(array_merge($a, $b));   // integer keys renumbered
print_r(array_replace($a, $b)); // integer keys preserved

?>

Output:

Array
(
    [0] => zero
    [1] => one
    [2] => ONE
    [3] => two
)
Array
(
    [0] => zero
    [1] => ONE
    [2] => two
)

See array_merge() for the full comparison.

Conclusion

In conclusion, the array_replace function in PHP provides a convenient way to update arrays by replacing their values with values from other arrays. With its simple syntax and flexible parameters, it can be used in a variety of situations, making it an essential tool for PHP developers. Whether you're working on a simple project or a complex one, the array_replace function can help streamline your development process and make your code more efficient.

Practice