array_rand

(PHP 4, PHP 5, PHP 7, PHP 8)

array_randToma una o varias claves, al azar en un array

Descripción

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

Selecciona uno o varios valores al azar en un array y devuelve la o las claves de estos valores.

Precaución

Esta función no genera valores criptográficamente seguros y no debe ser utilizada para fines criptográficos o fines que requieran que los valores devueltos sean impredecibles.

Si se requiere aleatoriedad criptográficamente segura, se puede utilizar el Random\Randomizer con el motor Random\Engine\Secure. Para casos de uso simples, las funciones random_int() y random_bytes() proporcionan una API conveniente y segura respaldada por el CSPRNG del sistema operativo.

Parámetros

array

El array de entrada. No puede estar vacío.

num

Especifica el número de entradas que se desean recuperar. Debe ser mayor a cero e inferior o igual a la longitud de array.

Valores devueltos

Cuando se recupera una sola entrada, la función array_rand() devuelve la clave de una entrada elegida al azar. De lo contrario, se devolverá un array de claves de entradas aleatorias. Esto permite hacer una selección al azar de claves, o bien de valores. Si se devuelven varias claves, entonces lo serán en el orden en que estaban en el array original.

Errores/Excepciones

Lanza una ValueError si array está vacío, o si num está fuera de rango.

Historial de cambios

Versión Descripción
8.0.0 array_rand() ahora lanza una ValueError si num está fuera de rango; anteriormente, se generaba un E_WARNING y la función devolvía null.
8.0.0 array_rand() ahora lanza una ValueError si array está vacío; anteriormente, se generaba un E_WARNING y la función devolvía null.
7.1.0 El algoritmo interno de generación aleatoria ha sido modificado para usar el generador de números aleatorios »  Mersenne Twister en lugar de la función aleatoria libc

Ejemplos

Ejemplo #1 Ejemplo con 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";
?>

Ver también