PHP Iterables

A function that loops over "a collection of things" often does not actually care whether that collection is a plain array or a custom object built to be looped over -- both can be walked with foreach. PHP's iterable type hint captures exactly that idea: it accepts either an array or any Traversable object, letting a function accept both without extra work.

In this page:

What Counts as Iterable
Using iterable as a Parameter Type
Using iterable as a Return Type
The One-Time-Use Nature of Generators
iterable vs array: Choosing the Right Type Hint

Syntax

php

function function_name(iterable $items): iterable {
    foreach ($items as $item) {
        yield $item;
    }
}

is_iterable($value);

What Counts as Iterable

Two kinds of values satisfy the iterable type: any plain PHP array, and any object that implements the built-in Traversable interface (which includes both the Iterator interface and Generator functions) -- both can be the target of a foreach loop.

Note: Think of iterable as "anything foreach can walk through", rather than trying to memorize every specific class that qualifies.

Warning: A plain object that does NOT implement Traversable, even if it holds a collection of data internally, does not satisfy the iterable type hint.

Example: What Counts as Iterable

php

<?php
// Define the function `gen` with no parameters
function gen() {
    yield 1;
    yield 2;
}
// Print a detailed dump (with types) of `is_iterable([1, 2, 3])`
var_dump(is_iterable([1, 2, 3]));
// Print a detailed dump (with types) of `is_iterable(gen())`
var_dump(is_iterable(gen()));
?>

Using iterable as a Parameter Type

Type-hinting a function parameter as iterable instead of array signals that the function will only ever loop over the input with foreach, and does not require it to specifically be a real array -- making the function usable with a wider range of inputs, including large generators.

Note: Choose iterable over array for any function that genuinely only needs to loop through its input once and never needs array-specific operations like count() or array_map().

Warning: A function hinted as iterable cannot safely call array-only functions like count(), sort(), or array_push() on its parameter, since a Generator does not support them.

Example: Using iterable as a Parameter Type

php

<?php
// Define the function `printAll` taking `iterable $items`
function printAll(iterable $items) {
    // Loop over `$items`, binding each item to `$item`
    foreach ($items as $item) {
        // Print `$item . "\n"` to the output
        echo $item . "\n";
    }
}
// Call `printAll([1, 2, 3])`
printAll([1, 2, 3]);
?>

Using iterable as a Return Type

A function can also declare its return type as iterable, signaling that it will return something loopable -- either a real array it builds up, or a generator using yield -- without committing to which specific one, giving the function's implementation flexibility to change later.

Note: Returning a generator (yield) instead of a built array can save significant memory for large datasets, since values are produced one at a time instead of all being held in memory at once.

Warning: Code calling a function with an iterable return type should not assume the result supports array functions like count() -- treat it as foreach-only unless you know the concrete type.

Example: Using iterable as a Return Type

php

<?php
// Define the function `numbers` with no parameters
function numbers(): iterable {
    yield 1;
    yield 2;
    yield 3;
}
// Loop over `numbers()`, binding each item to `$n`
foreach (numbers() as $n) {
    // Print `$n . "\n"` to the output
    echo $n . "\n";
}
?>

The One-Time-Use Nature of Generators

Unlike an array, which can be looped over as many times as you like, a Generator can only be iterated once -- once a foreach loop over a generator finishes, looping over that same generator object again produces nothing at all, since its internal position has already advanced to the end.

Note: If a value received as iterable needs to be used more than once, convert it to a real array first with iterator_to_array(), which "materializes" a generator into a reusable array.

Warning: Looping an already-exhausted generator a second time does not raise an error -- it simply produces zero iterations, which can silently hide a bug.

Example: The One-Time-Use Nature of Generators

php

<?php
function gen() {
    yield 1;
    yield 2;
}
$g = gen();
foreach ($g as $v) { echo $v . "\n"; }
foreach ($g as $v) { echo "second pass: $v\n"; } // never runs
echo "done";
?>

iterable vs array: Choosing the Right Type Hint

Use array specifically when a function genuinely needs array-only capabilities like count(), sorting, or random access by key.

Use iterable when a function only ever needs to walk through the values once with foreach -- accepting a wider range of input types at no real cost.

Note: When designing a new function, default to the narrowest type hint that still does the job -- iterable if a simple foreach loop is all you need, array if you genuinely need array-specific behavior.

Warning: Widening an existing function's parameter from array to iterable is usually a safe change; narrowing from iterable to array can break any caller currently passing in a generator.

Example: iterable vs array: Choosing the Right Type Hint

php

<?php
function countItems(array $items) {
    return count($items); // needs real array capabilities
}
function printItems(iterable $items) {
    foreach ($items as $item) {
        echo $item . "\n"; // only ever loops
    }
}
echo countItems([1, 2, 3]);
?>

Chapter Quiz — Complete all 24 topics to unlock

0/24 topics done

Complete these topics first:

← Previous Lesson PHP Include & Require Next Lesson → PHP with HTML & CSS