関数の概要
array_unshift は、PHPの配列操作関数の一つで、指定した配列の先頭に1つ以上の要素を追加するために使用します。この関数を使うと、元の配列の最初の位置に要素を挿入でき、元の配列のインデックスが自動的に調整されます。文字通り「配列の先頭に要素を押し込む」イメージです。
パラメータの説明
array（参照渡し）: 要素を追加したい元の配列を指定します。この配列が直接変更されます。values（複数指定可能）: 配列の先頭に追加する1つ以上の値を指定します。複数の値を指定した場合は、左から順に配列の先頭に追加されます。
戻り値
array_unshift は、追加後の配列の要素数（int）を返します。失敗した場合は false が返りますが、通常は成功すると考えて問題ありません。
使用例
基本的な使い方
<?php
$fruits = ['apple', 'banana'];
array_unshift($fruits, 'orange');
print_r($fruits);
?>
この例では、”orange” を配列 $fruits の先頭に追加しています。結果は ['orange', 'apple', 'banana'] となります。
複数の要素を先頭に追加する
<?php
$numbers = [3, 4, 5];
array_unshift($numbers, 1, 2);
print_r($numbers);
?>
この例では、”1″ と “2” の2つの値を先頭に追加しています。結果は [1, 2, 3, 4, 5] となります。
連想配列に対する利用例
<?php
$user = ['name' => 'Taro', 'age' => 30];
array_unshift($user, 'male');
print_r($user);
?>
連想配列でも使えますが、数値のキーが追加されるため注意が必要です。この例では新たに数値キーの 0 => 'male' が追加され、既存のキーは維持されます。
関連する関数
array_push– 配列の末尾に要素を追加する関数array_shift– 配列の先頭の要素を取り出し、配列から削除する関数array_pop– 配列の末尾の要素を取り出し、配列から削除する関数array_splice– 配列の任意の位置に要素を挿入・削除する高度な配列操作関数
まとめ
array_unshift は、PHPで配列の先頭に要素を簡単に追加できる便利な関数です。複数要素の追加も可能で、配列の順序を自由に変更したいときに役立ちます。特に、キュー操作やスタックのような先頭・末尾の取り扱いが必要な場面で活躍します。実務でも多用される基本的な配列関数の一つなので、使い方をしっかり押さえておきましょう。
