Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Types and Type Handling

The PHP iterable type

Reference for the PHP iterable pseudo-type: what it accepts, is_iterable(), iterating generators and iterators, and how it relates to Traversable.

iterable is a type declaration meaning "something you can loop over with foreach". It accepts either an array or any object that implements Traversable, which includes generators, Iterator and IteratorAggregate implementations and classes such as ArrayObject.

Use it when a function only needs to loop over its input once and does not care whether the data sits in memory in an array or is produced lazily. It was added in PHP 7.1. Since PHP 8.2 it is simply an alias for the union array|Traversable.

PHP
function total(iterable $numbers): int
{
    $sum = 0;
    foreach ($numbers as $n) {
        $sum += $n;
    }
    return $sum;
}

Try it

PHP One function, many sources

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP is_iterable(), keys and iterator_to_array()

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
function process(iterable $items): void { /* ... */ }
function make(): iterable { yield 1; }
is_iterable($value): bool
iterator_to_array(Traversable $it, bool $preserve_keys = true): array
Value Accepted by iterable?
array yes
Generator, Iterator, IteratorAggregate, ArrayObject yes
Plain stdClass or other object without Traversable no
string, int, null no

Usage notes

  • A generator can be traversed only once. If you loop over it a second time you get an exception ("Cannot traverse an already closed generator"). Convert it to an array first if you need several passes.
  • Do not call array functions on an iterable. array_map() and count() need arrays (count() also accepts Countable). Use iterator_to_array(), iterator_count() or write a foreach.
  • Duplicate keys. iterator_to_array() keeps the last value for repeated keys when it preserves keys (see the second example); pass false to get a list.
  • Return type iterable lets an implementation return an array now and switch to a generator later without breaking callers, but callers can only use foreach on the result.
  • Narrowing subclasses: a child method may declare the narrower array or Traversable return type; parameters may widen to iterable.
  • iterable cannot be used as a class name and does not combine with array or Traversable in a union (it would be redundant, so PHP rejects it).
  • Large data. Streaming a file or a database result through a generator with an iterable parameter keeps memory flat. See Generators.