Yield Expression

The yield keyword in PHP is a control flow operator used within a function to transform it into a Generator. Instead of returning a single value and destroying the function’s execution context, yield pauses the function’s execution, emits a value to the calling iteration, and preserves the function’s internal state (including local variables and the instruction pointer) so execution can be resumed exactly where it left off.

When a function contains at least one yield statement, invoking that function does not execute its body immediately. Instead, it implicitly returns an internal Generator object, which implements the Iterator interface.

Syntax Variations

The yield expression can be utilized in several syntactical forms depending on the desired emission structure:

1. Yielding a Value Emits a standard value. The generator automatically assigns a sequential integer key starting from 0.

function yieldValue() {
    yield 'value';
}

2. Yielding a Key-Value Pair Emits both a specific key and a value, mirroring the behavior of associative arrays.

function yieldKeyValue() {
    yield 'key' => 'value';
}

3. Yielding Null Calling yield without an argument emits null.

function yieldNull() {
    yield;
}

4. Yielding by Reference By prefixing the generator function declaration with an ampersand (&), the generator yields values by reference. This allows the caller (e.g., a foreach loop) to directly modify the internal variables of the generator.

function &yieldByReference() {
    $value = 10;
    yield $value;
}

5. Yield Delegation (yield from) The yield from operator delegates the yielding process to an iterable (which encompasses primitive arrays and objects implementing the Traversable interface, such as another Generator). It exhausts the provided iterable before continuing the current generator’s execution.

function yieldDelegation() {
    yield from [1, 2, 3];
    yield from anotherGenerator();
}

Yield as an Evaluated Expression

In PHP, yield is an expression, meaning it evaluates to a value. This facilitates bidirectional communication between the generator and the caller.

When the caller invokes the Generator::send($value) method, execution resumes, and the yield expression evaluates to the value passed via send(). If the generator is resumed via Generator::next() or a standard foreach loop, the yield expression evaluates to null.

function bidirectionalYield() {
    // Emits 'initial', then pauses. 
    // Upon resumption via send(), $injected receives the sent value.
    $injected = yield 'initial'; 
    
    // Emits the injected value back to the caller
    yield $injected; 
}

Precedence and Associativity

Since PHP 7.0, yield is a right-associative operator. This means basic assignments can be written without parentheses, and the PHP engine will correctly parse the expression. Parentheses are only required to dictate precedence when combining the result of a yield expression with other operators with higher precedence.

// Valid: Right-associative assignment
$result = yield 'value'; 

// Requires parentheses: Concatenation has higher precedence
$concatenated = (yield 'value') . ' appended string';

Return Values and yield from Evaluation

A generator function terminates, and the Generator object is marked as closed, when it reaches a return statement or the end of the function block. A return statement inside a generator does not emit a value to the iteration; instead, it sets the generator’s return value, which can be retrieved post-iteration using Generator::getReturn().

Crucially, when using yield from with a delegated generator, the yield from expression evaluates to the return value of that delegated generator. This provides a mechanism for sub-generators to pass a final result back to the delegating generator once their iteration is exhausted.

function subGenerator() {
    yield 'A';
    yield 'B';
    return 'Sub-generator complete';
}

function mainGenerator() {
    // Yields 'A', then 'B'. 
    // Once subGenerator finishes, $status receives its return value.
    $status = yield from subGenerator(); 
    
    // Yields 'Sub-generator complete'
    yield $status; 
}

Master PHP with Deep Grasping Methodology!

Learn More