PHP マニュアル: 配列から一つ以上のキーをランダムに取得する

説明

intstringarray array_rand(array $array, int $num = 1)

一つ以上のランダムなエントリを配列から取り出し、取り出したエントリのキーを返します。

警告

この関数が生成する値は、暗号学的にセキュアではありません。そのため、これを暗号や、戻り値を推測できないことが必須の値として使っては いけません。

暗号学的にセキュアな乱数が必要な場合は、Random\Randomizer を Random\Engine\Secure と一緒に使いましょう。簡単なユースケースの場合、random_int と random_bytes 関数が、オペレーティングシステムの CSPRNG を使った、便利で安全な API を提供します。

警告

この関数は、乱数のソースとしてグローバルな Mt19937 (メルセンヌ・ツイスター) インスタンスを使用するため、グローバルな Mt19937 を使用する他のすべての関数と状態を共有します。これらの関数のいずれかを使用すると、スコープに関係なく、すべての他の関数のシーケンスも進みます。

mt_srand または srand に既知の値を指定してシードすることで再現可能なシーケンスを生成する場合、この関数からの出力も再現可能になります。

新しく書くコードでは、すべて Random\Randomizer のメソッドを使用することを推奨します。

パラメータ

array: 入力の配列。空配列にはできません。
num: 取得するエントリの数を指定します。 1以上 array の要素数以下である必要があります。

戻り値

エントリを一つだけ取得する場合、 array_rand はランダムなエントリのキーを返します。その他の場合は、ランダムなエントリのキーの配列を返します。これにより、ランダムな値だけではなくランダムなキーも配列から取得できるようになります。複数のキーが返される場合、配列に格納された順番と同じ順で返されます。

エラー / 例外

array が空か num が範囲外の値の場合に、 ValueError がスローされます。

変更履歴

バージョン	説明
8.0.0	`num` が範囲外の値の場合に、 ValueError がスローされるようになりました。これより前のバージョンでは、 `E_WARNING` が発生し、`null` を返していました。
8.0.0	`array` が空の場合に、 ValueError がスローされるようになりました。これより前のバージョンでは、 `E_WARNING` が発生し、`null` を返していました。
7.1.0	内部的なランダム化アルゴリズムは、 libc の rand 関数ではなく、 » メルセンヌツイスタ乱数生成器を使うように変更されました

例

例1 array_rand の例

<?php
srand((float) microtime() * 10000000);
$input = array("ネオ", "モーフィアス", "トリニティ", "サイファー", "タンク");
$rand_keys = array_rand($input, 2);
echo $input[$rand_keys[0]] . "\n";
echo $input[$rand_keys[1]] . "\n";
?>

注意

注意: srand または mt_srand によりランダム数生成器にシードを与える必要はありません。これは、この処理が自動的に行われるためです。

参考

Random\Randomizer::pickArrayKeys
Random\Randomizer::shuffleArray