is_iterable()

Introducción

is_iterable() es una función integrada de PHP (disponible desde PHP 7.1) que indica si un valor puede recorrerse con un bucle foreach. Devuelve true exactamente para dos tipos de valores:

• Arrays — todo array es iterable.
• Objetos que implementan la interfaz Traversable — en la práctica, esto incluye objetos que implementan Iterator o IteratorAggregate, así como generadores (funciones que utilizan yield).

Todo lo demás — cadenas de texto, enteros, booleanos, null y objetos simples (como stdClass) — no es iterable, aunque intuitivamente parezca "similar a una lista". Esta página cubre la sintaxis, qué se considera iterable, los errores más comunes y cuándo usar is_iterable() resulta realmente útil.

Sintaxis

is_iterable(mixed $value): bool

Recibe un único argumento, $value, y devuelve un booleano:

Desde PHP 8.0 también existe un pseudotipo equivalente, iterable, que puede usarse como declaración de tipo — véase Cuándo usarlo más abajo.

Ejemplo básico

$var1 es un array, por lo que es iterable. $var2 es una cadena de texto — aunque se puede acceder a sus caracteres uno a uno, no puede usarse con foreach, de modo que is_iterable() devuelve false.

Qué se considera iterable

Los casos interesantes son los objetos. Un objeto solo es iterable si implementa Traversable (directamente o mediante Iterator/IteratorAggregate), o si es un generador. Un objeto simple no lo es.

<?php
function genFn() {
    yield 1;
    yield 2;
}

class MyCollection implements IteratorAggregate {
    private array $items = [1, 2, 3];

    public function getIterator(): Iterator {
        return new ArrayIterator($this->items);
    }
}

var_dump(is_iterable([1, 2, 3]));      // bool(true)  array
var_dump(is_iterable(genFn()));        // bool(true)  generator
var_dump(is_iterable(new MyCollection())); // bool(true)  Traversable
var_dump(is_iterable("hello"));        // bool(false) string
var_dump(is_iterable(42));             // bool(false) int
var_dump(is_iterable(new stdClass())); // bool(false) plain object
var_dump(is_iterable(null));           // bool(false) null
?>

La conclusión clave: un stdClass (o cualquier objeto sin Traversable) devuelve false, aunque foreach sí pueda recorrer sus propiedades públicas. is_iterable() informa deliberadamente solo de los valores que son iterables por contrato, no por accidente.

Errores comunes

• Las cadenas de texto no son iterables. Una cadena es un escalar, no una colección, por lo que is_iterable("abc") es false. Para comprobar si un valor es una cadena, usa is_string().
• Los objetos simples fallan. is_iterable(new stdClass()) es false. Si solo quieres saber si un valor es cualquier objeto, usa is_object(); si específicamente necesitas un objeto recorrible, is_iterable() es la llamada correcta.
• No es lo mismo que is_array(). is_array() es true solo para arrays y rechaza generadores y objetos Traversable. Usa is_iterable() cuando quieras aceptar tanto arrays como objetos iteradores.
• null devuelve false. Pasar un valor no inicializado o null es seguro — simplemente devuelve false en lugar de lanzar un error.

Cuándo usarlo

Usa is_iterable() como una cláusula de guarda antes de un foreach, de modo que una función pueda aceptar tanto un array como un iterador perezoso sin fallar con entradas incorrectas:

<?php
function sumAll(mixed $data): int {
    if (!is_iterable($data)) {
        throw new InvalidArgumentException('Expected an iterable.');
    }

    $total = 0;
    foreach ($data as $value) {
        $total += $value;
    }
    return $total;
}

echo sumAll([1, 2, 3, 4]), "\n"; // 10

function counter() {
    yield 5;
    yield 10;
}
echo sumAll(counter()), "\n";     // 15
?>

La misma función maneja tanto un array simple como un generador, porque ambos satisfacen is_iterable().

A menudo la opción más limpia es la declaración de tipo iterable (PHP 7.1+), que permite a PHP aplicar la restricción por ti para que puedas omitir la comprobación manual por completo:

<?php
function sumAll(iterable $data): int {
    $total = 0;
    foreach ($data as $value) {
        $total += $value;
    }
    return $total;
}
?>

Recurre a la función is_iterable() cuando el valor sea mixed y quieras ramificar en tiempo de ejecución; recurre al type hint iterable cuando la iterabilidad sea un requisito obligatorio del parámetro.

Conclusión

is_iterable() responde a una pregunta precisa: ¿puede este valor ser recorrido por un bucle foreach? Devuelve true para arrays y objetos Traversable (incluidos generadores) y false para todo lo demás. Úsala como guarda en tiempo de ejecución para entradas mixed, prefiere el type hint iterable cuando la iterabilidad sea obligatoria y recuerda que es más estricta de lo que parece — las cadenas de texto y los objetos simples no son iterables. Para comprobaciones relacionadas, consulta is_array(), is_object() y gettype().

Práctica