array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'function.array-rand.php', 1 => 'array_rand', 2 => 'Выбирает один или несколько случайных ключей из массива', ), 'up' => array ( 0 => 'ref.array.php', 1 => 'Функции для работы с массивами', ), 'prev' => array ( 0 => 'function.array-push.php', 1 => 'array_push', ), 'next' => array ( 0 => 'function.array-reduce.php', 1 => 'array_reduce', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/array/functions/array-rand.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

array_rand

(PHP 4, PHP 5, PHP 7, PHP 8)

array_rand — Выбирает один или несколько случайных ключей из массива

Описание

array_rand(array $array, int $num = 1): int|string|array

Функция выбирает в массиве один или несколько случайных элементов. Для одного элемента возвращается ключ, а для нескольких элементов — массив ключей.

Предостережение

Функция не создаёт безопасные для криптографических целей значения, поэтому функцию нельзя использовать в криптографических целях или ожидать возврата значения, которое невозможно угадать.

Безопасные для криптографических целей случайные последовательности создаёт композиция класса Random\Randomizer с движком Random\Engine\Secure. В простых сценариях пользуются функциями random_int() и random_bytes() с удобным и безопасным API-интерфейсом, который поддерживается безопасным для криптографических целей CSPRNG-генератором псевдослучайных чисел операционной системы.

Предостережение

Функция создаёт случайные последовательности через глобальный экземпляр генератора псевдослучайных чисел на основе алгоритма Mt19937 «Вихрь Мерсе́на» поэтому разделяет состояние с остальными функциями, которые генерируют случайности через глобальный генератор. Вызов каждой такой функции продвигает последовательность, независимо от области вызова.

Функция выдаст предсказуемые одинаковые последовательности, если инициализировать генератор псевдослучайных чисел функцией mt_srand() или srand() одним и тем же значением.

В новом коде случайные последовательности лучше генерировать через объект Random\Randomizer.

Список параметров

array

Входной массив. При передаче пустого массива функция выдаст ошибку.

num

Количество элементов для выбора. Функция выдаст ошибку, если значение меньше единицы или превышает размер массива array.

Возвращаемые значения

При запросе одного элемента функция array_rand() возвращает случайный ключ, а для нескольких элементов — массив ключей. Логика возврата случайных ключей, а не значений, расширяет выбор случайных элементов: значения, которые получают из исходного массива по случайным ключам, также составляют случайную выборку. В выходном массиве ключи сохраняют относительный порядок, который соответствует порядку элементов в исходном массиве.

Ошибки

Функция выбрасывает ошибку ValueError, если в параметр array передали пустой массив или значение параметра num выходит за пределы диапазона.

Список изменений

Версия Описание
8.0.0 Функция array_rand() теперь выбрасывает ошибку ValueError, если значение параметра num выходит за пределы диапазона; раньше функция выдавала ошибку уровня E_WARNING и возвращала значение null.
8.0.0 Функция array_rand() теперь выбрасывает ошибку ValueError, если в параметр array передали пустой массив; раньше функция выдавала ошибку уровня E_WARNING и возвращала значение null.
7.1.0 Внутренний алгоритм выбора случайных элементов изменился с функции rand библиотеки libc на генератор случайных чисел на базе » Вихря Мерсе́нна.

Примеры

Пример #1 Пример выбора случайных ключей массива функцией array_rand()

<?php

$input = array("Neo", "Morpheus", "Trinity", "Cypher", "Tank");
$rand_keys = array_rand($input, 2);
echo $input[$rand_keys[0]] . "\n";
echo $input[$rand_keys[1]] . "\n";

?>

Смотрите также