PHP array_replace() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Array

Definition

In PHP, array_replace() replaces the values of the first array with values from other arrays that have the same keys.

Keys that do not exist in the first array are added. Later arrays win over earlier ones, and keys are preserved.

Syntax

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

PHP
$result = array_replace($original, $changes);
CallWhat it does
array_replace(["a", "b", "c"], [1 => "B"])Returns ["a", "B", "c"].
array_replace(["x" => 1], ["y" => 2])Returns ["x" => 1, "y" => 2].
array_replace($a, $b, $c)Applies $b and then $c on top of $a.

Unlike array_merge(), numeric keys are not renumbered. A key in a later array replaces the same key in an earlier one.

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

Parameters

ParameterDescription
arrayRequired. The base array whose values may be replaced.
replacementsOptional. One or more arrays whose values replace or add to the base array.

Return Value

Return ValueDescription
arrayA new array with replacements applied. The original arrays are unchanged.

PHP Examples

Example 1 — Replace a Value by Key

Change the item at index 1 of a list.

PHP
<?php
$letters = ["a", "b", "c"];

$result = array_replace($letters, [1 => "B"]);

echo implode(", ", $result), PHP_EOL;

How It Works

  1. Create the base list. It holds a, b and c.
  2. Prepare a replacement. Key 1 has the new value B.
  3. Call array_replace(). Index 1 is replaced and the others stay.
  4. Print the result. The original $letters is unchanged.

Example 2 — New Keys and Multiple Replacements

Missing keys are added, and later arrays win.

PHP
<?php
echo json_encode(array_replace(["x" => 1], ["y" => 2])), PHP_EOL;

$result = array_replace([1, 2, 3], [1 => "a"], [1 => "b", 3 => "d"]);
echo json_encode($result), PHP_EOL;

How It Works

  1. Use a new key. y does not exist in the first array, so it is added.
  2. Pass several replacements. They are applied from left to right.
  3. Check key 1. It becomes "a" first and then "b".
  4. Add key 3. A new item d is added at the end.

Example 3 — array_replace() vs array_merge()

Numeric keys are treated differently by the two functions.

PHP
<?php
$a = [5 => "a"];
$b = [5 => "b"];

echo json_encode(array_replace($a, $b)), PHP_EOL;
echo json_encode(array_merge($a, $b)), PHP_EOL;

How It Works

  1. Use the same numeric key. Both arrays have key 5.
  2. Run array_replace(). The value at key 5 is replaced by b.
  3. Run array_merge(). The numeric keys are renumbered, so both values are kept.
  4. Choose by need. Use replace for overwriting by key, and merge for combining lists.

Frequently Asked Questions

It replaces values in the first array with values from the other arrays that use the same keys. New keys are added.
array_replace() keeps numeric keys and replaces by key. array_merge() renumbers numeric keys and appends.
No. It returns a new array.
Only on the top level. Use array_replace_recursive() for nested arrays.
The last array wins.

Next: array_replace_recursive()

array_replace_recursive() replaces values of the first array with values from other arrays.

array_replace_recursive() 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