array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.array-rand.php', 1 => 'array_rand', 2 => 'Escolhe uma ou mais chaves aleatórias de um array', ), 'up' => array ( 0 => 'ref.array.php', 1 => 'Funções para Array', ), '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' => 'pt_BR', '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 — Escolhe uma ou mais chaves aleatórias de um array

Descrição

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

Escolhe aleatóriamente um ou mais itens de um array, e retorna a chave (ou chaves) do itens selecionados.

Cuidado

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.

Cuidado

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.

Parâmetros

array

O 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.

Valor Retornado

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.

Erros/Exceções

Lança uma exceção ValueError se array estiver vazio, ou se num estiver fora do intervalo permitido.

Registro de Alterações

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.

Exemplos

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

Veja Também