Generator return expressions

Though PHP 5.5 enriched the language by introducing generator functions functionality, it lacked the return expressions alongside their yielded values. This inability of generator functions to specify return values limited their usefulness with coroutines. The PHP 7 version addressed this limitation by adding support for the return expressions. Generators are basically interruptible functions, where the yield statement flags the interruption point. Let's take a look at the following simple generator, written in the form of a self-invoking anonymous function:

$letters = (function () {
  yield 'A';
  yield 'B';
  return 'C';
})();

// Outputs: A B
foreach ($letters as $letter) {
  echo $letter;
}

// Outputs: C
echo $letters->getReturn();

Though the $letters variable is defined as a self-invoking anonymous function, the yield statements are preventing immediate function execution, turning the function into the generator. Generator itself stands still until we try to iterate over it. Once the iteration kicks in, generator yields value A followed by value B, but not C. What this means is that when used in the foreach construct, the iteration will only encompass yielded values, not the returned ones. Once the iteration is done, we are free to call the getReturn() method to retrieve the actual return value. Calling the getReturn() method prior to iterating over generator results cannot get the return value of a generator that hasn't returned an exception.

The great thing about the generators is that they are not a one-way street; they are not limited to only yielding values, they can accept them as well. By being the instances of a \Generator class, they operate with several useful methods, two of which are getReturn and send. The send method enables us to send values back to the generator, which turns the one-way communication from the generator to the caller into a two-way channel between the two, effectively, turning generators into coroutines. The addition of the getReturn method empowered generators with the return statements, giving more flexibility with coroutines.