(PHP 4, PHP 5, PHP 7, PHP 8)
array_rand — Escolhe uma ou mais chaves aleatórias de um array
Escolhe aleatóriamente um ou mais itens de um array, e retorna a chave (ou chaves) do itens selecionados.
Esta função não gera valores criptograficamente seguros e não deve ser usada para propósitos criptográficos ou fins que exijam que os valores retornados sejam impossíveis de adivinhar.
Se aleatoriedade criptograficamente segura for necessária, a classe Random\Randomizer pode ser usada com o mecanismo Random\Engine\Secure. Para casos de uso simples, as funções random_int() e random_bytes() fornecem uma API conveniente e segura que é garantida pelo CSPRNG do sistema operacional.
arrayO array de entrada. Não pode ser vazio.
num Especifica quantos elementos deseja obter. Deve ser maior que zero, e menor ou igual ao comprimento do array.
Se estiver selecionando apenas um elemento, array_rand() retorna a chave para este elemento aleatório. De outra forma, ele retorna um array com as chaves desses elementos selecionados. Assim é possível selecionar os elementos pelas chaves no array assim como valores aleatórios. Se múltiplas chaves forem retornadas, elas serão retornadas na ordem em que estavam presentes no array original.
Lança uma exceção ValueError se array estiver vazio, ou se num estiver fora do intervalo permitido.
| Versão | Descrição |
|---|---|
| 8.0.0 | array_rand() agora lança uma exceção ValueError se num estiver fora do intervalo; anteriormente um E_WARNING era emitido, e a função retornava null. |
| 8.0.0 | array_rand() agora lança uma exceção ValueError se array estiver vazio; anteriormente um E_WARNING era emitido, e a função retornava null. |
| 7.1.0 | O algoritmo de embaralhamento interno foi alterado para usar o Gerador de Números Aleatórios » Mersenne Twister em vez da função rand da libc. |
Exemplo #1 Exemplo de 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";
?>