PHP Iterables

Introducción a los iterables de PHP

En PHP, un iterable es cualquier cosa que puedes recorrer con foreach. Eso incluye dos tipos de valores:

1. Arrays — la estructura de datos habitual que almacena una colección ordenada de pares clave/valor.
2. Objetos Traversable — objetos que PHP sabe cómo recorrer, porque implementan la interfaz integrada Traversable (en la práctica a través de Iterator o IteratorAggregate, o como un generador).

PHP 7.1 añadió el pseudo-tipo iterable para que puedas declarar "dame cualquier cosa sobre la que pueda hacer foreach" sin importar si quien llama pasa un array o un objeto. Esta página explica qué cuenta como iterable, cómo crear y recorrer cada tipo, y cuándo usar los iterables perezosos que proporcionan los generadores.

Este capítulo se basa en PHP Arrays y el bucle foreach. Si eres nuevo en alguno de ellos, léelos primero.

Arrays: el iterable más común

Los arrays vienen en dos variantes, y la única diferencia es el tipo de clave que usan:

• Un array indexado almacena valores bajo claves enteras automáticas, comenzando en 0. Consulta Arrays indexados.
• Un array asociativo usa cadenas (o enteros que tú eliges) como claves. Consulta Arrays asociativos.

Un solo array puede mezclar ambos estilos, y los valores pueden ser de cualquier tipo de dato.

Crear y acceder a arrays

Crea un array con corchetes y luego lee un valor por su clave:

PHP definir y acceder a un array

<?php
$fruits  = ["apple", "banana", "cherry"];           // indexed
$student = ["name" => "John Doe", "age" => 25];      // associative

echo $fruits[0] . "\n";        // apple   (first element, index 0)
echo $student["name"] . "\n";  // John Doe

Salida:

apple
John Doe

Ten en cuenta que los arrays indexados comienzan en cero, por lo que $fruits[0] es el primer elemento.

Iterar un array con foreach

foreach es la forma idiomática de recorrer un iterable. Para un array indexado normalmente solo necesitas el valor; para un array asociativo generalmente quieres tanto la clave como el valor:

PHP iterar sobre arrays

<?php
$fruits  = ["apple", "banana", "cherry"];
$student = ["name" => "John Doe", "age" => 25];

foreach ($fruits as $fruit) {
    echo $fruit . "\n";
}

foreach ($student as $key => $value) {
    echo "$key: $value\n";
}

Salida:

apple
banana
cherry
name: John Doe
age: 25

Funciones útiles para arrays

PHP incluye docenas de funciones de array. Algunas que usarás constantemente:

• array_keys($arr) — devuelve todas las claves como un nuevo array.
• array_values($arr) — devuelve todos los valores, reindexados desde 0.
• count($arr) — devuelve el número de elementos.
• sort($arr) — ordena los valores de forma ascendente en el lugar, devolviendo true en caso de éxito (no devuelve el array ordenado).
• in_array($needle, $arr) — true si el valor existe.

PHP funciones de array en acción

<?php
$scores = [40, 10, 30];

echo count($scores) . "\n";              // 3
print_r(array_keys($scores));            // [0, 1, 2]

sort($scores);                            // modifies $scores in place
print_r($scores);                         // [10, 30, 40]

Salida:

3
Array
(
    [0] => 0
    [1] => 1
    [2] => 2
)
Array
(
    [0] => 10
    [1] => 30
    [2] => 40
)

El pseudo-tipo iterable

iterable no es una clase — es una indicación de tipo que significa "array o Traversable". Úsala en un parámetro o tipo de retorno cuando tu función solo necesite iterar, y no quieras obligar a quien llama a convertir sus datos en un array simple primero.

PHP indicación de tipo iterable

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

echo sumAll([1, 2, 3]) . "\n";          // works with an array

function countToThree(): iterable {     // a generator is also iterable
    yield 1;
    yield 2;
    yield 3;
}
echo sumAll(countToThree()) . "\n";     // works with a Traversable too

Salida:

6
6

La ventaja: sumAll() acepta un array normal y un flujo generado de forma perezosa sin código adicional. Consulta Funciones PHP para más información sobre las indicaciones de tipo.

Generadores: iterables perezosos

Un generador es una función que usa yield en lugar de return. Produce valores de uno en uno, solo cuando el bucle pide el siguiente, por lo que nunca construye toda la colección en memoria. Esto es ideal para secuencias grandes o infinitas.

PHP ejemplo de generador

<?php
function range_lazy(int $start, int $end): iterable
{
    for ($i = $start; $i <= $end; $i++) {
        yield $i;          // pauses here and resumes on the next iteration
    }
}

foreach (range_lazy(1, 5) as $value) {
    echo $value . " ";
}
echo "\n";

Salida:

1 2 3 4 5

Como nada se almacena, range_lazy(1, 1_000_000) usa la misma cantidad mínima de memoria que range_lazy(1, 5).

Objetos iterables personalizados con Iterator

Cuando quieres control total sobre cómo se recorre un objeto, implementa la interfaz Iterator. Requiere cinco métodos que foreach llama internamente: rewind(), valid(), current(), key() y next().

PHP Iterator personalizado

<?php
class EvenNumbers implements Iterator
{
    private int $position = 0;

    public function __construct(private array $items) {}

    public function rewind(): void  { $this->position = 0; }
    public function valid(): bool   { return isset($this->items[$this->position]); }
    public function current(): mixed { return $this->items[$this->position]; }
    public function key(): mixed    { return $this->position; }
    public function next(): void    { $this->position++; }
}

$evens = new EvenNumbers([2, 4, 6]);
foreach ($evens as $n) {
    echo $n . " ";
}
echo "\n";

Salida:

2 4 6

La mayor parte del tiempo un generador es más sencillo que una clase Iterator completa — recurre a Iterator solo cuando necesitas comportamiento personalizado de rebobinado/clave o quieres exponer la iteración como parte de la API pública de un objeto.

Comprobar si un valor es iterable

Usa is_iterable() para comprobar en tiempo de ejecución si un valor puede pasarse a foreach:

PHP comprobación con is_iterable

<?php
var_dump(is_iterable([1, 2, 3]));                 // bool(true)
var_dump(is_iterable("a string"));                // bool(false)
var_dump(is_iterable((function () { yield 1; })())); // bool(true)

Salida:

bool(true)
bool(false)
bool(true)

Conclusión

"Iterable" en PHP simplemente significa recorrible con foreach — y eso incluye arrays, objetos Iterator/IteratorAggregate y generadores por igual. Usa arrays simples para colecciones ordinarias, la indicación de tipo iterable para escribir funciones que acepten cualquiera de ellos, y generadores cuando la memoria sea importante o la secuencia sea grande. Con estas herramientas puedes modelar datos de forma eficiente y mantener tus APIs flexibles.

Práctica