PHP 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 {}

Tired of Poor PHP Skills? Fix That With Deep Grasping!Learn More

Functions

Methods

Constructors and Destructors

Object-Oriented Types

Properties

Constants

Parameters

Variables

Traits

Attributes

Control Flow

Loops

Error Handling

Namespaces

File Inclusion

Built-In Types

Comments

Access Operators

Conditional Operators

Comparison Operators

Logical Operators

Type Operators

Arithmetic Operators

String Operators

Assignment Operators

Sign & Increment Operators

Special Unary Operators

Bitwise Operators

Type Declarations

Runtime Type Checking

Generators and Iterable

Variance Rules in Inheritance

Default Values

​Type Declarations

​Runtime Type Checking

​Generators and Iterable

​Variance Rules in Inheritance

​Default Values

Type Declarations

Runtime Type Checking

Generators and Iterable

Variance Rules in Inheritance

Default Values