【PHP8.x】array_unshift関数の使い方

<?php

/**
 * array_unshift の多次元配列での使用例を示します。
 *
 * この関数は、既存の多次元配列の先頭に新しい要素（この例では別の配列）を追加し、
 * その結果と新しい配列の要素数を標準出力に表示します。
 */
function demonstrateArrayUnshiftWithMultidimensional(): void
{
    // 初期状態の多次元配列を定義します。
    $products = [
        ['id' => 101, 'item' => 'Product A', 'price' => 100],
        ['id' => 202, 'item' => 'Product B', 'price' => 250],
    ];

    echo "--- 元の多次元配列 ---" . PHP_EOL;
    print_r($products);
    echo PHP_EOL;

    // 配列の先頭に追加する新しい要素（別の配列）を定義します。
    $newProduct = [
        'id' => 303,
        'item' => 'Product C',
        'price' => 150
    ];

    echo "--- 追加する単一の要素 ---" . PHP_EOL;
    print_r($newProduct);
    echo PHP_EOL;

    // array_unshift を使用して、多次元配列の先頭に新しい要素を追加します。
    // array_unshift は最初の引数（&$array）を「参照渡し」で受け取るため、
    // $products 配列自体が変更されます。
    // 戻り値は、操作後の配列の新しい要素数（int型）です。
    $newCount = array_unshift($products, $newProduct);

    echo "--- array_unshift 実行後の多次元配列 ---" . PHP_EOL;
    echo "追加後の配列の要素数: " . $newCount . PHP_EOL;
    print_r($products);
    echo PHP_EOL;

    // 複数の要素を一度に追加する例
    echo "--- 複数の要素を一度に追加する例 ---" . PHP_EOL;

    $orders = [
        ['order_id' => 1, 'customer' => 'Alice'],
        ['order_id' => 2, 'customer' => 'Bob'],
    ];

    echo "元の配列:" . PHP_EOL;
    print_r($orders);
    echo PHP_EOL;

    $newOrder1 = ['order_id' => 3, 'customer' => 'Charlie'];
    $newOrder2 = ['order_id' => 4, 'customer' => 'David'];

    echo "追加する複数の要素:" . PHP_EOL;
    print_r($newOrder1);
    print_r($newOrder2);
    echo PHP_EOL;

    // array_unshift は可変長引数（...$values）を受け取るため、複数の要素を一度に追加できます。
    // 引数に指定された順序で配列の先頭に挿入されます。（$newOrder1 が一番先頭、次に $newOrder2）
    $newCountMultiple = array_unshift($orders, $newOrder1, $newOrder2);

    echo "array_unshift (複数の要素) 実行後の配列:" . PHP_EOL;
    echo "追加後の配列の要素数: " . $newCountMultiple . PHP_EOL;
    print_r($orders);
    echo PHP_EOL;
}

// 関数を実行して、array_unshift の動作を確認します。
demonstrateArrayUnshiftWithMultidimensional();

PHPのarray_unshift関数は、既存の配列の先頭に一つ以上の要素を追加する際に使用します。この関数は、最初の引数である$arrayを「参照渡し」で受け取るため、元の配列自体が直接変更されます。追加したい要素は$valuesとして複数指定することが可能で、引数に指定された順序で配列の先頭に挿入されます。関数は、操作後の配列の新しい要素数を整数（int）で返します。

このサンプルコードは、array_unshiftが多次元配列に対してどのように動作するかを示しています。最初に、商品情報を格納する多次元配列$productsを用意し、その先頭に新しい商品の配列$newProductを追加する例を紹介しています。array_unshiftの実行後には$products配列の先頭に$newProductが追加され、追加後の配列の要素数が表示されます。さらに、複数の注文情報を一度に配列の先頭へ追加する例も含まれており、$newOrder1、$newOrder2の順で$orders配列の先頭に挿入される様子が確認できます。これにより、既存の配列の先頭に効率的に要素を追加し、その結果を確認できることがわかります。

<?php

/**
 * array_unshift関数の動作を示すサンプルコードです。
 *
 * array_unshift関数は、指定された配列の先頭に一つまたは複数の要素を追加します。
 * 追加された要素には数値キーが割り当てられ、既存の数値キーの要素は再インデックスされます。
 * 既存の文字列キー（連想配列のキー）は変更されず保持されます。
 * 関数は新しい配列の要素数を返します。
 */

// 最初に定義する連想配列
$associativeArray = [
    'fruit' => 'banana',
    'color' => 'yellow',
    'origin' => 'Ecuador',
];

echo "--- 初期状態の配列 ---\n";
print_r($associativeArray);

// array_unshiftを使って配列の先頭に新しい要素を追加します
// この例では、連想配列に数値キーの要素が追加され、既存の連想キーはそのまま残ります。
// array_unshiftは追加された要素に0からの数値キーを割り当てます。
$newCount = array_unshift($associativeArray, 'apple', 'red');

echo "\n--- array_unshift実行後の配列 ---\n";
print_r($associativeArray);

echo "新しい配列の要素数: " . $newCount . "\n";

echo "\n--- 別の連想配列での挙動（数値キーが混在する場合） ---\n";
$mixedArray = [
    'first_item' => 'a',
    0 => 'b', // 数値キー
    'third_item' => 'c',
    1 => 'd', // 数値キー
];

echo "--- 初期状態の混在配列 ---\n";
print_r($mixedArray);

// array_unshiftで要素を追加
// 既存の文字列キー('first_item', 'third_item')は保持されます。
// 既存の数値キー(0, 1)は再インデックスされ、新しい要素に0からの数値キーが割り当てられます。
$newCountMixed = array_unshift($mixedArray, 'new_start_1', 'new_start_2');

echo "\n--- array_unshift実行後の混在配列 ---\n";
print_r($mixedArray);
echo "新しい配列の要素数: " . $newCountMixed . "\n";

?>

PHPのarray_unshift関数は、指定された配列の先頭に一つまたは複数の要素を追加する機能を提供します。最初の引数$arrayには操作対象の配列を渡します。この引数は参照渡しのため、関数が実行されると元の配列自体が直接変更されます。続く引数$valuesには、配列の先頭に追加したい要素を必要なだけ指定できます。関数は、要素追加後の配列の新しい要素数を整数値で返します。

この関数の重要な挙動として、追加される要素には0から始まる数値キーが割り当てられます。もし元の配列に数値キーの要素が含まれていた場合、それらは新しい要素の追加に伴い自動的に再インデックス（キーが振り直される）されます。特に連想配列の場合、既存の文字列キーを持つ要素はそのキーと値が変更されずに保持されます。これにより、連想配列の構造を保ちつつ、先頭に数値キーの新しい要素を追加できます。サンプルコードでは、連想配列の先頭に新たな要素が数値キーで追加され、元の連想キーが維持される挙動と、数値キーが混在する配列での再インデックスの様子が確認できます。