> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PHP 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`.
```php theme={"dark"}
function yieldValue() {
yield 'value';
}
```
**2. Yielding a Key-Value Pair**
Emits both a specific key and a value, mirroring the behavior of associative arrays.
```php theme={"dark"}
function yieldKeyValue() {
yield 'key' => 'value';
}
```
**3. Yielding Null**
Calling `yield` without an argument emits `null`.
```php theme={"dark"}
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.
```php theme={"dark"}
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.
```php theme={"dark"}
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`.
```php theme={"dark"}
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.
```php theme={"dark"}
// 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.
```php theme={"dark"}
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;
}
```
Tired of Poor PHP Skills? Fix That With Deep Grasping!
Learn More
