Função PHP: array_rand

A função PHP array_rand() seleciona uma ou mais chaves aleatoriamente de um array. Ela não retorna os valores em si — retorna chaves, que você usa para ler os elementos correspondentes. Essa pequena distinção é a fonte de confusão mais comum com a função, por isso vale a pena ter isso em mente ao longo desta página.

array_rand() é a ferramenta certa quando você precisa escolher um item aleatório de uma lista (uma citação aleatória, um banner aleatório, uma pergunta aleatória) ou obter um subconjunto aleatório de um array maior sem modificar ou reordenar o original.

Sintaxe

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

O tipo de retorno depende de $num:

• Quando $num é 1 (ou omitido), retorna uma única chave — um int para um array numérico ou uma string para uma chave de string.
• Quando $num é 2 ou mais, retorna um array de chaves.

Selecionando um único elemento

O uso mais comum é obter um valor aleatório. Chame array_rand() para obter uma chave e use essa chave para indexar novamente no array:

array_rand($colors) retorna uma única chave aleatória (um índice inteiro neste caso), que é usada para ler a cor correspondente. Os dois passos são frequentemente combinados em uma linha: $colors[array_rand($colors)].

Selecionando vários elementos

Passe um segundo argumento para obter várias chaves. O resultado é um array de chaves, e as chaves são retornadas na mesma ordem em que aparecem no array original — apenas quais chaves são escolhidas é aleatório, não a sua ordem:

<?php

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

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

?>

Como array_rand() retorna chaves e não valores, a maneira típica de mapeá-las de volta para valores é usar array_map:

<?php

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

print_r($picked);

?>

Valor de retorno e chaves string

Um equívoco frequente é que array_rand() sempre retorna inteiros. Isso não é verdade — ela retorna a chave que selecionou, preservando seu tipo original. Para um array associativo, isso significa chaves string:

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

?>

Armadilhas comuns

• Retorna chaves, não valores. array_rand($arr) fornece uma chave; você ainda precisa de $arr[$key] para obter o valor.
• Array vazio. Chamar array_rand() em um array vazio lança um ValueError (PHP 8+) ou emite um aviso e retorna null em versões anteriores. Verifique o array primeiro.
• $num fora do intervalo. Pedir mais elementos do que o array contém gera um ValueError.
• Não é criptograficamente seguro. array_rand() é adequado para embaralhar banners ou amostrar dados, mas nunca o use para selecionar tokens de sessão, senhas ou qualquer coisa sensível à segurança. Use random_int() com um CSPRNG para isso.

Funções relacionadas

• shuffle() — reordena aleatoriamente todos os elementos de um array no lugar.
• str_shuffle() — embaralha aleatoriamente os caracteres de uma string.
• rand() e mt_rand() — geram um inteiro aleatório em um intervalo.
• array_slice() — extrai uma parte contígua de um array.

Conclusão

array_rand() é uma forma compacta de selecionar chaves aleatórias de um array — uma quando $num é omitido, um array delas quando você passa um número. Lembre-se de que ela retorna chaves (preservando seu tipo original, inteiro ou string), que as chaves escolhidas mantêm a ordem original do array e que ela não é adequada para aleatoriedade sensível à segurança.

Prática