PHP array_unshift() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Array

Definition

In PHP, array_unshift() adds one or more values to the beginning of an array.

It changes the original array and returns the new number of items. Existing numeric keys are renumbered.

Syntax

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

PHP
$count = array_unshift($queue, "first");
CallWhat it does
array_unshift($list, "a")Adds "a" to the front of the array.
array_unshift($list, "x", "y")Adds two values, keeping their order.
$n = array_unshift($list, "z")Stores the new item count in $n.

array_unshift() is the opposite of array_shift(). It is slower than array_push() on large arrays because every item has to move.

Library declarations
PHP
array_unshift(array &$array, mixed ...$values): int

Parameters

ParameterDescription
arrayRequired. The array to add values to. It is passed by reference.
valuesRequired. One or more values to put at the start of the array.

Return Value

Return ValueDescription
intThe new number of items in the array.

PHP Examples

Example 1 — Add to the Front

Put a new value at the start of a list.

PHP
<?php
$letters = ["b", "c"];
$count = array_unshift($letters, "a");

echo "Count: ", $count, PHP_EOL;
echo implode(", ", $letters), PHP_EOL;

How It Works

  1. The list starts with "b" and "c".
  2. array_unshift() inserts "a" at the front.
  3. It returns the new size of the array, which is 3.
  4. The list now reads a, b, c.

Example 2 — Several Values and Keys

Multiple values keep their order, and numeric keys are renumbered.

PHP
<?php
$nums = [1, 2];
array_unshift($nums, "x", "y");
echo implode(", ", $nums), PHP_EOL;

$data = ["k" => "v", 5 => "five"];
array_unshift($data, "new");
echo json_encode($data), PHP_EOL;

How It Works

  1. Passing "x" and "y" together puts them at the front in that order.
  2. In the second array the string key "k" is kept.
  3. The numeric key 5 is renumbered to 1, and the new item takes key 0.
  4. json_encode() shows an object because the keys are not a simple 0, 1, 2 list.

Example 3 — Recent History

Keep the most recent pages first, limited to three entries.

PHP
<?php
$history = ["page2", "page1"];

array_unshift($history, "page3");
array_unshift($history, "page4");
$history = array_slice($history, 0, 3);

echo implode(" > ", $history), PHP_EOL;

How It Works

  1. The history starts with two pages, newest first.
  2. Each visit adds the new page to the front of the list.
  3. After two additions there are four items.
  4. array_slice() keeps just the first three, so the oldest page is dropped.

Frequently Asked Questions

It adds one or more values to the start of an array and returns the new item count.
array_unshift() adds to the beginning of the array. array_push() adds to the end.
Yes. Numeric keys are renumbered from 0. String keys are preserved.
No. It changes the array you pass in and returns the new length as an integer.
Build a new array with [$item, ...$array]. This creates a copy with the item at the front.

Next: array_values()

array_values() returns all the values of an array with fresh numeric keys starting from 0.

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