Yield From Expression

The yield from expression delegates the execution of a generator to another iterable structure, such as an array, a Traversable object, or another generator. It allows a parent generator to yield all values from a sub-iterable directly to the calling context without requiring an explicit foreach loop to extract and re-yield those values.

yield from <iterable>;

Execution Mechanics

When the PHP engine evaluates a yield from expression, it temporarily suspends the execution of the current generator and transfers control to the provided <iterable>.

1. Value Emission: Every value and key produced by the sub-iterable is passed directly to the outer generator’s caller.
2. Key Preservation: yield from strictly preserves the keys yielded by the delegated iterable. If an array with specific string or integer keys is passed to yield from, those exact keys are emitted to the caller.
3. Bidirectional Communication: If the delegated iterable is another generator, yield from establishes a transparent conduit. Calls to Generator::send() or Generator::throw() on the parent generator are forwarded directly to the active sub-generator.

Expression Evaluation and Return Values

Both yield and yield from are expressions. However, they evaluate to different values based on their mechanics. While a standard yield expression evaluates to the value passed back to the generator via Generator::send(), a yield from expression evaluates to the return value of the delegated iterable once it is completely exhausted.

• Generators: If the delegated iterable is a generator that terminates with a return statement, the yield from expression evaluates to that returned value.
• Arrays and Traversables: If the delegated iterable is an array or a standard Traversable object, the yield from expression evaluates to null.

function subGenerator(): Generator {
    yield 'A';
    yield 'B';
    return 'Sub-generator execution finished';
}

function parentGenerator(): Generator {
    // Delegates yielding to an array. Evaluates to null.
    yield from [1, 2]; 

    // Delegates yielding to another generator. Evaluates to the generator's return value.
    $returnValue = yield from subGenerator(); 
    
    yield $returnValue;
}

// Iteration output: 1, 2, 'A', 'B', 'Sub-generator execution finished'

Syntax Rules

• yield from can only be used within a function, method, or closure, which implicitly marks that callable as a Generator.
• It accepts exactly one expression that must evaluate to an iterable type. Passing a non-iterable scalar or object will result in a fatal Error with the message “Can use ‘yield from’ only with arrays and Traversables”.
• Because it is an expression, its result can be assigned directly to a variable (e.g., $result = yield from $iterable;). Parentheses are not required for simple assignment, but they are strictly required when the yield from expression is evaluated within larger operations (e.g., $result = 5 + (yield from $iterable);).

Master PHP with Deep Grasping Methodology!

Learn More