Definition and Usage

PHP Version
4+

The array_merge() function merges one or more arrays in order to create a new array.

This function is useful when you need to merge multiple arrays into one.

Features

  • Allows you to merge multiple arrays in any desired order.
  • Does not modify the original arrays; instead, it returns a new array containing the merged result.
  • Appends the elements of each array in sequence.

Basic Example

PHP 
/* Merging Indexed Arrays */
$array1 = [1, 2, 3];
$array2 = [4, 5, 6];

// Merge the two arrays
$result = array_merge($array1, $array2);

print_r($result);
/*
Output:
    Array
    (
        [0] => 1
        [1] => 2
        [2] => 3
        [3] => 4
        [4] => 5
        [5] => 6
    )
*/

/* Merging Associative Arrays */
$assoc_array1 = ['a' => 'red', 'b' => 'green'];
$assoc_array2 = ['c' => 'blue', 'd' => 'yellow'];

// Merge the two associative arrays
$assoc_result = array_merge($assoc_array1, $assoc_array2);

print_r($assoc_result);
/*
Output:
    Array
    (
        [a] => red
        [b] => green
        [c] => blue
        [d] => yellow
    )
*/

Syntax

PHP 
array_merge(array array1, array2, array3, ...): array

Parameters

$array1, $array2, $array3, ...: One or more arrays to merge. This function accepts one or more arrays as arguments and merges them sequentially into a new array.

Return Values

Returns the merged array. If no parameters are passed, it returns an empty array.

  • If the arrays being merged are associative arrays (arrays with string keys), values from later arrays overwrite the values from previous arrays with the same string keys.
  • If the arrays being merged have numeric keys (indexed arrays), values are appended to the end of the resulting array without overwriting.
  • The numeric keys in the resulting array are re-indexed starting from 0 in ascending order.

Changelog

Changelog of the array_merge() Function
Before PHP 7.4.0 At least one array parameter was required when calling the function. Calling it without any parameters (or passing null) would trigger a warning in PHP.
Since PHP 7.4.0 The function can be called without any parameters. It returns an empty array if no parameters are given. However, passing null will cause a fatal error.
Before PHP 7.4.0 
$result = array_merge();
var_dump($result); // Output: Warning: array_merge() expects at least 1 parameter...

$result = array_merge(null);
var_dump($result); // Output: Warning: array_merge() expects at least 1 parameter...
Since PHP 7.4.0 
$result = array_merge();
var_dump($result); // Output: array(0) { }

$result = array_merge(null);
var_dump($result); // Output: Fatal error: Uncaught TypeError:

Handling Duplicate Elements

To use the array_merge() function correctly, it is important to understand how it handles duplicate elements. Let’s look at examples showing how it works with duplicate keys or indexes.

  • Handling duplicate string keys
  • Handling duplicate numeric keys (indexes)
  • Handling both string and numeric keys

Handling Duplicate String Keys

When the arrays being merged have the same string keys, the values from the later arrays overwrite those from the earlier arrays. In other words, the later values replace the earlier ones.

PHP 
$array1 = ['a' => 'apple', 'b' => 'banana'];
$array2 = ['b' => 'blueberry', 'c' => 'cherry'];

$result = array_merge($array1, $array2);

print_r($result);
/*
Output:
    Array
    (
        [a] => apple
        [b] => blueberry
        [c] => cherry
    )
*/
  • Both $array1 and $array2 have the duplicate string key 'b'.
  • The array_merge() function overwrites the value for the duplicate key 'b' with the value from the later array ($array2), which is 'blueberry'.

Handling Duplicate Numeric Keys (Indexes)

When the arrays being merged have numeric keys (indexes), the later values are appended without overwriting the original values. For numeric keys, values are added with new keys instead of overwriting.

PHP 
$array1 = [0 => 'apple', 1 => 'banana'];
$array2 = [1 => 'blueberry', 2 => 'cherry'];

$result = array_merge($array1, $array2);

print_r($result);
/*
Output:
    Array
    (
        [0] => apple
        [1] => banana
        [2] => blueberry
        [3] => cherry
    )
*/
  • Both $array1 and $array2 have the duplicate numeric key 1.
  • The array_merge() function does not overwrite the value for the numeric key 1 but instead appends the new values with incremented numeric keys (2 and 3).

Handling Both String and Numeric Keys

PHP 
$array1 = ['apple', 'banana', 'color' => 'red'];
$array2 = ['green', 'orange', 'color' => 'orange', 'shape' => 'circle'];

$result = array_merge($array1, $array2);
print_r($result);
/*
Output:
    Array
    (
        [0] => apple
        [1] => banana
        [color] => orange
        [2] => green
        [3] => orange
        [shape] => circle
    )
*/
  • The string key 'color' is overwritten by the value from $array2, which is 'orange'.
  • The numeric keys 2 and 3 are assigned to the appended values 'green' and 'orange' from $array2.

Understanding how array_merge() handles duplicate numeric and string keys is crucial for predicting the resulting merged array and maintaining the correct data structure.

Merging Multidimensional Associative Arrays

The example below demonstrates how to merge multidimensional associative arrays using the array_merge() function.

PHP 
// First array
$array1 = [
    'name' => 'John Doe',
    'age' => 30,
    'address' => [
        'street' => '123 Main Street',
        'city' => 'Anytown',
        'state' => 'CA'
    ]
];

// Second array
$array2 = [
    'phone' => '123-456-7890',
    'email' => 'johndoe@example.com'
];

// Merge the two arrays
$result = array_merge($array1, $array2);

// Output the result
print_r($result);
/*
Output:
    Array
    (
		[name] => John Doe
	    [age] => 30
	    [address] => Array
	        (
	            [street] => 123 Main Street
	            [city] => Anytown
	            [state] => CA
	        )
	    [phone] => 123-456-7890
	    [email] => johndoe@example.com
    )
*/

The above example is designed with the following points in mind:

  • Ensure that the keys in the first and second arrays do not overlap.
  • The address information in the first array is preserved and not overwritten by the second array.
  • The phone number and email information from the second array are added to the first array.

You can apply this example to merge multidimensional associative arrays in various situations.

References

See also