PHP array_unshift() 導致數字鍵重排的陷阱與應對策略

現象復現

array_unshift() 用於在數組開頭插入元素。但鮮為人知的是：若數組鍵為純數字或可轉換為數字的字符串，該函數會將所有數字鍵重新從 0 開始連續索引，導致原有鍵值關係丟失。

 "dddddddddddd",
    "112" => array("one" => "orange", "two" => "hhhhh"),
    "113" => array("one" => "orange", "two" => "hhhhh"),
    "oooo" => "jjjjj"
);
print_r($a);
echo "
";

array_unshift($a, "aaaaaaaaa");
print_r($a);
echo "
";
?>

輸出結果

Array
(
    [111] => dddddddddddd
    [112] => Array (...)
    [113] => Array (...)
    [oooo] => jjjjj
)
Array
(
    [0] => aaaaaaaaa
    [1] => dddddddddddd      // 原鍵 111 變為 1
    [2] => Array (...)      // 原鍵 112 變為 2
    [3] => Array (...)      // 原鍵 113 變為 3
    [oooo] => jjjjj         // 字符串鍵不變
)

根本原因

PHP 內部將「純數字字符串鍵」（如 "112"）視為整數鍵處理。array_unshift() 的實現邏輯是：重新建立一個從 0 開始的連續索引數組，並按順序複製原數組值。因此，所有整數鍵（含數字字符串鍵）均被重排；非數字字符串鍵（如 "oooo"）保持不變。

影響範圍

• array_unshift()
• array_push()（不影響鍵，但僅追加）
• array_shift()、array_pop()（同樣重排數字鍵）
• array_splice()（視參數而定）

應對策略

方案一：使用鍵名前綴避免純數字鍵（推薦）

$a = array(
    'id_111' => "dddddddddddd",
    'id_112' => array(...),
    'id_113' => array(...),
    'oooo' => "jjjjj"
);
array_unshift($a, "aaaaaaaaa");
// 鍵名保持不變

方案二：手動重建數組保持鍵值

$new = ['new_key' => 'aaaaaaaaa'] + $a;
// 或
$new = array_merge(['new_key' => 'aaaaaaaaa'], $a);
// 注意：array_merge 也會重排數字鍵，+ 運算符保留鍵

方案三：使用 ArrayObject 或 Collection 類

$coll = new \ArrayObject($a, \ArrayObject::ARRAY_AS_PROPS);
$coll->offsetSet('new_key', 'aaaaaaaaa'); // 不會重排

方案四：插入後手動恢復鍵（不推薦，效能差）

$keys = array_keys($a);
array_unshift($a, 'aaaaaaaaa');
// 需手動映射回原鍵，極易出錯

最佳實踐建議

1. 設計階段避免純數字鍵：業務主鍵統一加前綴（如 uid_、pid_），從源頭消除隱患。
2. 需在頭部插入且保持鍵：使用 ['new' => $val] + $arr 或 array_merge（注意合併行為差異）。
3. 文檔化標註：在團隊編碼規範中明確標註 array_unshift/shift/splice 的鍵重排行為，Code Review 時重點關注。

總結

array_unshift() 的數字鍵重排行為是 PHP 歷史設計決策，而非 Bug。理解其機制、規避純數字鍵、選擇正確合併操作符（+ 保留鍵、array_merge 重排），才能避免生產環境中難以排查的數據錯位問題。