PHPのarray_unshift()関数とは？使い方とサンプルコードを解説

PHPのarray_unshift()関数は、既存の配列の先頭（冒頭）に、1つ以上の要素を追加するための関数です。新しい要素は数値キー（インデックス）が自動的に割り当てられ、元の文字列キーを持つ要素はそのまま維持されます。

構文

array_unshift(arr, val1, val2, val3)

パラメータ

• arr − 要素を追加する対象となる配列。必須。

• val1 − 先頭に挿入する値。必須。

• val2 − 先頭に挿入する値。省略可能。複数の値を指定した場合、指定した順序どおりに配列の先頭へ追加されます。

• val3 − 先頭に挿入する値。省略可能。

戻り値

array_unshift()関数は、要素を追加した後の配列の新しい要素数（整数）を返します。なお、この関数は引数として渡された配列そのものを直接変更します。

サンプルコード①：戻り値を確認する

まずは、戻り値として返される要素数を確認してみましょう。

<?php
$arr = array("p"=>"one","q"=>"two");
print_r(array_unshift($arr,"three"));
?>

出力結果

もともと2つの要素だった配列に「three」を追加したため、新しい要素数である 3 が出力されます。

3

サンプルコード②：追加後の配列内容を確認する

次に、array_unshift()実行後の配列の中身を print_r() で出力して確認します。

<?php
$arr = array("p"=>"one","q"=>"two");
array_unshift($arr,"three");
print_r($arr);
?>

出力結果

Array
(
[0] => three
[p] => one
[q] => two
)

この出力結果から、以下のことがわかります。

• 新しく追加された「three」には、数値キー [0] が自動的に割り当てられます。

• 元の連想配列の文字列キー「p」「q」とその値は、変更されずそのまま保持されます。

• 追加された要素は、常に配列の先頭に配置されます。

まとめ

array_unshift()関数を使うことで、配列の末尾ではなく先頭に要素を簡単に追加できます。複数の値を一度に渡すことも可能で、キュー（待ち行列）のように先入れ先出しのデータ構造を実装したい場合などにも活用できます。逆に、配列の末尾へ要素を追加したい場合は array_push() 関数を使用してください。