PHP array_unshift Function | Add Elements at Starting of Array

PHP array_unshift is an inbuilt Function in PHP. It adds one or more elements in the beginning of an array. Also, it adds new elements starting with the 0 index. In this article, we will discuss the PHP array_unshift Function. Also, we will discuss a few examples of using it.

Note: PHP array_push Function adds new elements at the end of the array.

Syntax

int array_unshift($array, $val1, $val2, $val3….)

Parameters

The PHP array_unshift Function expects atleast two parameters. However, you can pass multiple parameters to the function depending on the number of new elements. The description of the parameters is as follows:

• $array: The first parameter is a mandatory array in which the function adds new elements.
• $val1, $val2…$valN: You need to pass atleast one value to the function. However, if you want to insert more than one element in the array, then they are passed as comma separated parameters.

Return Value

The function returns the total number of elements in the new array. The function adds new elements starting from 0 index always. However, it does not modify any literal keys in the array. This will be further explained in the examples.

Examples

Let’s discuss a few examples of using the array_unshift Function in PHP.

Example 1: Simple Numerical Array

For instance, consider a simple numerical array.

<?php
	$testArray = array(1, 2, 3, 4);
	
	//Inserting 5 in the beginning
	array_unshift($testArray, 5);
	print_r($testArray);
	/*
	Array
	(
	    [0] => 5
	    [1] => 1
	    [2] => 2
	    [3] => 3
	    [4] => 4
	)
	*/

	//Inserting More elements in the beginning
	array_unshift($testArray, 6, 7);
	print_r($testArray);
	/*
	Array
	(
	    [0] => 6
	    [1] => 7
	    [2] => 5
	    [3] => 1
	    [4] => 2
	    [5] => 3
	    [6] => 4
	)
	*/
?>

You can observe the following in the above example:

• The function adds new elements to the beginning of the array.
• The array is re-indexed and new elements always start from 0 index.
• Also, you can pass multiple values to the function and the function will add the values at the beginning of the array.

Example 2: Associative Array

For example, consider an associative array.

<?php
	$testArray = array(
		'a' => 'apple',
		'b' => 'ball',
		'c' => 'cat'
	);
	
	//Inserting mango in the beginning
	array_unshift($testArray, 'mango');
	print_r($testArray);
	/*
	Array
	(
	    [0] => mango
	    [a] => apple
	    [b] => ball
	    [c] => cat
	)
	*/

?>

In the above example, notice that the function adds new elements always to the beginning. Also, it does not change the existing string keys in an associative array.

Expert Tip: Preserving Keys

The PHP array_unshift Function always re-indexes the array after adding new elements to the beginning. You can preserve the existing keys by using the (+) operator. This is explained in the example below:

<?php
	$testArray = array(
		'a' => 'apple',
		'b' => 'ball',
		'c' => 'cat'
	);
	
	$testArray = array('m' => 'mango') + $testArray;
	print_r($testArray);
	/*
	Array
	(
	    [m] => mango
	    [a] => apple
	    [b] => ball
	    [c] => cat
	)
	*/

?>

Conclusion

In this article, we discussed the PHP array_unshift Function. You can read more about it on the Official PHP Documentation. Also, you can learn about more PHP Array Functions on Concatly.