iterable

iterable is a built-in pseudo-type in PHP, introduced in version 7.1, that acts as a strict type alias for the union array|Traversable. While plain objects (such as stdClass or user-defined classes) can be iterated over using a foreach loop to access visible properties, they do not satisfy the iterable type constraint. A value is only considered iterable if it is a primitive array or an object that explicitly implements the Traversable interface.

Because Traversable is an internal engine interface that cannot be implemented directly in userland PHP, an object satisfies the iterable pseudo-type if it implements either the Iterator or IteratorAggregate interfaces.

Type Declarations

iterable can be used as a parameter type, a return type, and (as of PHP 7.4) a class property type.

Parameter Type:

function process(iterable $collection): void {
    foreach ($collection as $key => $value) {
        // Iteration logic
    }
}

Return Type:

function generateCollection(): iterable {
    return new ArrayIterator(['a', 'b', 'c']);
}

Property Type:

class CollectionHolder {
    public iterable $items;
}

Runtime Type Checking

PHP provides the is_iterable() function to verify at runtime whether a variable’s contents satisfy the iterable pseudo-type constraints.

var_dump(is_iterable([1, 2, 3]));                           // bool(true)
var_dump(is_iterable(new ArrayIterator([1, 2, 3])));        // bool(true)
var_dump(is_iterable((function() { yield 1; })()));         // bool(true)
var_dump(is_iterable(new stdClass()));                      // bool(false)

Generators and Iterable

Generator functions, which utilize the yield keyword, return a Generator object. Because the Generator class implements the Iterator interface, generator return values inherently satisfy the iterable type declaration.

function getValues(): iterable {
    yield 1;
    yield 2;
    yield 3;
}

Variance Rules in Inheritance

When extending classes or implementing interfaces, iterable adheres to PHP’s standard rules for type variance.

Covariance (Return Types): A child class can narrow a return type from iterable to a more specific type, such as array or a specific class implementing Traversable.

interface DataSource {
    public function read(): iterable;
}

class ArrayDataSource implements DataSource {
    // Valid covariance: narrowing iterable to array
    public function read(): array {
        return [1, 2, 3];
    }
}

Contravariance (Parameter Types): A child class can widen a parameter type from array or a specific Traversable implementation to the broader iterable pseudo-type.

class BaseProcessor {
    public function process(array $data): void {}
}

class AdvancedProcessor extends BaseProcessor {
    // Valid contravariance: widening array to iterable
    public function process(iterable $data): void {}
}

Default Values

When used as a parameter type, iterable allows for default values. This can be an array, null (if the type is nullable), or, as of PHP 8.1, an instantiated Traversable object utilizing new expressions in initializers.

// Valid: Array default
function executeWithArray(iterable $data = []): void {}

// Valid: Nullable default
function executeNullable(?iterable $data = null): void {}

// Valid (PHP 8.1+): Instantiated object default
function executeWithObject(iterable $data = new ArrayIterator([])): void {}

Master PHP with Deep Grasping Methodology!

Learn More