(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.
Esta função usa a instância global do Mt19937 (“Mersenne Twister”) como a fonte de aleatoriedade a por isso compartilha seu estado com todas as outras funções que usam o Mt19937 global. Usar qualquer uma destas funções avança a sequência para todas as outras funções, independentemente do escopo.
Gerar sequências repetíveis ao semear mt_srand() ou srand() com um valor conhecido também gerará saída repetível desta função.
Prefira usar métodos de Random\Randomizer em todo código novo.
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";
?>