PHP функция: array_rand

Функция PHP array_rand() случайным образом выбирает один или несколько ключей из array. Она не возвращает сами значения — она возвращает ключи, по которым затем можно получить соответствующие элементы. Это небольшое отличие является наиболее распространённым источником путаницы при работе с функцией, поэтому об этом стоит помнить на протяжении всей страницы.

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

Синтаксис

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

Тип возвращаемого значения зависит от $num:

• Когда $num равен 1 (или не указан), возвращается один ключ — int для числового array или string для строкового ключа.
• Когда $num равен 2 или больше, возвращается array ключей.

Выбор одного элемента

Наиболее распространённый сценарий использования — получение одного случайного значения. Вызовите array_rand(), чтобы получить ключ, а затем используйте этот ключ для обращения к array:

array_rand($colors) возвращает один случайный ключ (здесь целочисленный индекс), который используется для получения соответствующего цвета. Оба шага нередко объединяют в одну строку: $colors[array_rand($colors)].

Выбор нескольких элементов

Передайте второй аргумент, чтобы получить несколько ключей. Результатом будет array ключей, при этом ключи возвращаются в том же порядке, в котором они располагаются в исходном array — случаен лишь выбор ключей, но не их порядок:

<?php

$colors = ["red", "green", "blue", "yellow", "orange"];
$keys = array_rand($colors, 2); // e.g. [1, 4]

foreach ($keys as $key) {
    echo $colors[$key] . "\n";
}

?>

Поскольку array_rand() возвращает ключи, а не значения, типичный способ получить соответствующие значения — использовать array_map:

<?php

$colors = ["red", "green", "blue", "yellow", "orange"];
$picked = array_map(fn($k) => $colors[$k], (array) array_rand($colors, 2));

print_r($picked);

?>

Возвращаемое значение и строковые ключи

Распространённое заблуждение состоит в том, что array_rand() всегда возвращает целые числа. Это не так — функция возвращает любой выбранный ключ, сохраняя его исходный тип. Для ассоциативного array это означает строковые ключи:

<?php

$fruit = ["a" => "apple", "b" => "banana", "c" => "cherry"];
$key = array_rand($fruit);

echo $key;          // e.g. "b" (a string key)
echo "\n";
echo $fruit[$key];  // e.g. "banana"

?>

Типичные ошибки

• Возвращаются ключи, а не значения. array_rand($arr) даёт ключ; чтобы получить значение, всё равно нужно обращаться через $arr[$key].
• Пустой array. Вызов array_rand() на пустом array вызывает ValueError (PHP 8+) или генерирует предупреждение и возвращает null в более старых версиях. Перед вызовом проверяйте array.
• $num выходит за допустимый диапазон. Запрос большего числа элементов, чем содержится в array, вызывает ValueError.
• Не является криптографически безопасным. array_rand() подходит для перемешивания баннеров или выборки данных, однако никогда не используйте её для выбора токенов сессий, паролей или чего-либо, критичного с точки зрения безопасности. Для этого используйте random_int() вместе с CSPRNG.

Связанные функции

• shuffle() — случайно переупорядочивает все элементы array на месте.
• str_shuffle() — случайно перемешивает символы string.
• rand() и mt_rand() — генерируют случайное целое число в заданном диапазоне.
• array_slice() — извлекает последовательную часть array.

Заключение

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

Практика