PHP array_push() 新增元素

array_push() 函數用來將一個或多個元素新增到陣列的尾端。

基本用法

<?php
$arr = [1, 2, 3];

array_push($arr, 4);
print_r($arr);  // [1, 2, 3, 4]

array_push($arr, 5, 6, 7);
print_r($arr);  // [1, 2, 3, 4, 5, 6, 7]
?>

語法

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

• $array：要修改的陣列（傳址）
• $values：要新增的值
• 回傳值：新的陣列長度

使用 [] 語法（推薦）

新增單一元素時，使用 [] 語法更簡潔且效能更好：

<?php
$arr = [1, 2, 3];

// 使用 array_push
array_push($arr, 4);

// 使用 [] 語法（推薦）
$arr[] = 5;

print_r($arr);  // [1, 2, 3, 4, 5]
?>

新增多個元素

新增多個元素時，array_push() 更方便：

<?php
$arr = [1, 2, 3];

// 使用 array_push
array_push($arr, 4, 5, 6);

// 使用 [] 語法需要多次呼叫
$arr[] = 7;
$arr[] = 8;
$arr[] = 9;

// 或使用展開運算子
$arr = [...$arr, 10, 11, 12];

print_r($arr);
?>

取得新長度

<?php
$arr = [1, 2, 3];

$newLength = array_push($arr, 4, 5);
echo $newLength;  // 5
?>

關聯陣列

array_push() 會自動使用數字索引：

<?php
$arr = ['a' => 1, 'b' => 2];

array_push($arr, 3);
print_r($arr);
// ['a' => 1, 'b' => 2, 0 => 3]

// 要新增關聯鍵值，直接賦值
$arr['c'] = 4;
?>

新增陣列元素

<?php
$arr = [1, 2, 3];

// 新增陣列作為一個元素
array_push($arr, [4, 5]);
print_r($arr);
// [1, 2, 3, [4, 5]]

// 如果要合併陣列，使用 array_merge 或展開運算子
$arr = [1, 2, 3];
$arr = array_merge($arr, [4, 5]);
// 或
$arr = [...$arr, 4, 5];
print_r($arr);
// [1, 2, 3, 4, 5]
?>

常見應用

收集資料

<?php
$results = [];

for ($i = 1; $i <= 5; $i++) {
    $results[] = $i * 2;
}

print_r($results);  // [2, 4, 6, 8, 10]
?>

建立佇列

<?php
$queue = [];

// 入隊
$queue[] = 'Task 1';
$queue[] = 'Task 2';
$queue[] = 'Task 3';

// 出隊
while (!empty($queue)) {
    $task = array_shift($queue);  // 從前面取出
    echo "Processing: $task\n";
}
?>

收集錯誤訊息

<?php
function validate(array $data): array {
    $errors = [];
    
    if (empty($data['name'])) {
        $errors[] = '名稱不能為空';
    }
    
    if (empty($data['email'])) {
        $errors[] = 'Email 不能為空';
    } else if (!filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
        $errors[] = 'Email 格式不正確';
    }
    
    if (empty($data['password'])) {
        $errors[] = '密碼不能為空';
    } else if (strlen($data['password']) < 8) {
        $errors[] = '密碼至少需要 8 個字元';
    }
    
    return $errors;
}

$data = ['name' => '', 'email' => 'invalid', 'password' => '123'];
$errors = validate($data);

if (!empty($errors)) {
    foreach ($errors as $error) {
        echo "- $error\n";
    }
}
?>

動態建立選項

<?php
$options = [];

$options[] = '<option value="">請選擇</option>';

$categories = ['電子產品', '服飾', '食品', '書籍'];

foreach ($categories as $index => $category) {
    $options[] = "<option value=\"$index\">$category</option>";
}

echo '<select>' . implode("\n", $options) . '</select>';
?>

相關函數

array_unshift() - 新增到開頭

<?php
$arr = [2, 3, 4];

array_unshift($arr, 1);
print_r($arr);  // [1, 2, 3, 4]

array_unshift($arr, -1, 0);
print_r($arr);  // [-1, 0, 1, 2, 3, 4]
?>

array_pop() - 從尾端移除

<?php
$arr = [1, 2, 3, 4];

$last = array_pop($arr);
echo $last;      // 4
print_r($arr);   // [1, 2, 3]
?>

array_shift() - 從開頭移除

<?php
$arr = [1, 2, 3, 4];

$first = array_shift($arr);
echo $first;     // 1
print_r($arr);   // [2, 3, 4]
?>

效能比較

<?php
$iterations = 100000;

// 使用 array_push
$arr = [];
$start = microtime(true);
for ($i = 0; $i < $iterations; $i++) {
    array_push($arr, $i);
}
$time1 = microtime(true) - $start;

// 使用 []
$arr = [];
$start = microtime(true);
for ($i = 0; $i < $iterations; $i++) {
    $arr[] = $i;
}
$time2 = microtime(true) - $start;

echo "array_push: {$time1}s\n";
echo "[] syntax: {$time2}s\n";
// [] 語法通常更快
?>

注意事項

<?php
// array_push 會修改原陣列
$arr = [1, 2, 3];
array_push($arr, 4);
// $arr 已經被修改

// 展開運算子會建立新陣列
$arr = [1, 2, 3];
$newArr = [...$arr, 4];
// $arr 不變，$newArr 是新陣列
?>