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-генератором псевдослучайных чисел операционной системы.

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

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";

?>

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