Definition and Usage

PHP Version
4+

The array_unshift() function prepends one or more elements to the beginning of an array—similar to inserting items at the front. This also increases the array's length.

This function does not return a new array; instead, it modifies the original array directly.
Additionally, it returns an integer representing the array's new length after the elements have been added.

Basic Example

PHP 
$array = [1, 2, 3];

// Add a single element to the beginning of the array.
array_unshift($array, 4);
print_r($array);
/*
Output:
    Array
    (
        [0] => 4
        [1] => 1
        [2] => 2
        [3] => 3
    )
*/

// Add multiple elements to the beginning of the array.
array_unshift($array, 5, 6, 7);
print_r($array);
/*
Output:
    Array
    (
        [0] => 5
        [1] => 6
        [2] => 7
        [3] => 4
        [4] => 1
        [5] => 2
        [6] => 3
    )
*/

Syntax

PHP 
array_unshift(array &$array, mixed $value1 [, mixed $value2 [, mixed $... ]]): int

Parameters

Parameters of the array_unshift() Function
&$array The array to which the values will be added.
$value1, $value2, $... One or more values to add to the beginning of the array.

Return Values

The return value represents the total number of elements in the array after the new elements have been added. This value is returned as an integer (e.g., 1, 2, 3, ...).

PHP 
$array = [1, 2, 3];

// Add an element to the beginning of the array and store the return value.
$total_elements = array_unshift($array, 4);
print_r($array);
/*
Output:
    Array
    (
        [0] => 4
        [1] => 1
        [2] => 2
        [3] => 3
    )
*/

echo 'Total number of elements in the array: ' . $total_elements;
// Output: Total number of elements in the array: 4

Practical Examples

Here are some examples of how to use the array_unshift() function.

Adding Multiple Elements

To add multiple elements to an array, simply pass them as separate arguments to the array_unshift() function, separated by commas.

PHP 
$fruits = ['apple', 'banana', 'cherry'];

// Add elements to the beginning of the array
array_unshift($fruits, 'date', 'elderberry');

// Display the array contents
print_r($fruits);
/*
Output:
    Array
    (
        [0] => date
        [1] => elderberry
        [2] => apple
        [3] => banana
        [4] => cherry
    )
*/

Reversing an Array Using array_unshift()

You can also use array_unshift() to reverse the order of elements in an array.

PHP 
$numbers = [1, 2, 3, 4, 5];
$reversed_numbers = [];

foreach ($numbers as $number) {
    array_unshift($reversed_numbers, $number);
}

print_r($reversed_numbers);
/*
Output:
    Array
    (
        [0] => 5
        [1] => 4
        [2] => 3
        [3] => 2
        [4] => 1
    )
*/
  1. First, the $numbers array is initialized with the values [1, 2, 3, 4, 5].
  2. An empty array $reversed_numbers is created to store the reversed values.
  3. A foreach() loop iterates through each value in $numbers, storing the current value in the $number variable.
  4. Inside the loop, array_unshift($reversed_numbers, $number) inserts the current number at the beginning of the $reversed_numbers array. As a result, each new value appears before the previous ones, effectively reversing the order.

By the end of the loop, the $reversed_numbers array holds the values in reverse order: [5, 4, 3, 2, 1].

This method demonstrates how to reverse an array manually using array_unshift().

Note!
PHP also provides a built-in function called array_reverse(), which is a simpler and more efficient way to reverse an array.

References

See also