PHP array_unshift() 在陣列開頭插入元素：重設數字索引、保留字串鍵與堆疊應用

函式簽名

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

• **參考傳遞** 修改原陣列
• 在**開頭**插入一或多個值，**順序保持** (第一個參數變新索引 0)
• **數字索引重設**為 0 起始連續，**字串鍵名保持不變**
• 回傳**新陣列長度**

基本範例

<?php
$arr = ['orange', 'banana'];
$len = array_unshift($arr, 'apple', 'raspberry');

var_dump($len); // 4
print_r($arr);
/*
Array
(
    [0] => apple
    [1] => raspberry
    [2] => orange
    [3] => banana
)
*/

// 關聯陣列：字串鍵不變，數字鍵重設
$assoc = ['a' => 1, 0 => 'x', 'b' => 2];
array_unshift($assoc, 'new');
print_r($assoc);
/*
Array
(
    [0] => new
    [1] => x      // 原索引 0 重設為 1
    [a] => 1      // 字串鍵 'a' 不變
    [b] => 2
)
*/

實戰：實作佇列 (FIFO) - 效能較差

$queue = [];
array_unshift($queue, 'task1'); // 入隊
array_unshift($queue, 'task2');
array_unshift($queue, 'task3');

$task = array_pop($queue); // 出隊 (從尾部取出)
// 此為「反向佇列」：unshift 入隊、pop 出隊
// 正確佇列應用 array_push 入隊、array_shift 出隊

> ⚠️ **效能警告**：`array_unshift`/`array_shift` 需重設所有數字索引，**O(n)**。大量資料請用 `SplQueue` (雙向鏈表，**O(1)*)。

進階：保留關聯鍵名的前置插入

function assocUnshift(array &$array, array $prepend): void
{
    $array = $prepend + $array; // Union 運算子：左邊鍵優先，保留所有鍵名
}

$data = ['b' => 2, 'c' => 3];
assocUnshift($data, ['a' => 1]);
// ['a'=>1, 'b'=>2, 'c'=>3]  索引不重設，鍵名完整保留

相關函式對比

函式	位置	索引重設	回傳
`array_unshift`	開頭	數字重設、字串保留	新長度
`array_push`	結尾	數字重設、字串保留	新長度
`array_shift`	開頭移除	數字重設、字串保留	被移除值
`array_pop`	結尾移除	數字重設、字串保留	被移除值

---

原文摘自 zuodefeng 筆記