A generator’s return value needs getReturn, exactly once

A generator may return a value as well as yielding, and the value is only readable after the generator has finished.

function readCsv(string $path): Generator
{
    $rows = 0;

    foreach ($lines as $line) {
        $rows++;
        yield str_getcsv($line);
    }

    return $rows;
}

$g = readCsv($path);
foreach ($g as $row) { /* ... */ }
$g->getReturn();     // 412

// called before completion: Exception

The pattern is useful for a summary that is only knowable at the end — a row count, a checksum, a total — and it is the one part of the generator API that most people never encounter. Calling getReturn before the generator has completed throws rather than returning null, which is the right failure and means the call belongs after the loop rather than beside it.