【PHP8.x】getReturnメソッドの使い方

getReturnメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年10月16日

基本的な使い方

getReturnメソッドは、PHP 7.0.0以降で利用可能なGeneratorクラスに属し、ジェネレーター関数が最終的に返した値を取得するために実行するメソッドです。PHPのジェネレーター関数は、yieldキーワードを使って一時的に値を生成しながら処理を中断・再開できる特殊な関数で、特に大量のデータを扱う際や、処理の遅延評価を行いたい場合にメモリ効率の良い方法として利用されます。ジェネレーター関数は、yieldで値を生成するだけでなく、通常の関数と同様にreturn文を使って最終的な値を返すことができます。

このgetReturnメソッドは、ジェネレーターがすべてのyield処理を終え、完全に実行が完了した後にreturn文で返された値を正確に取得するために使用されます。もしジェネレーターがまだ実行中で、すべての処理が完了していない状態でこのメソッドを呼び出した場合、nullが返されます。したがって、ジェネレーターが生成する値をすべて消費し終えるか、明示的にジェネレーターが終了したことを確認した後にこのメソッドを使用することが重要です。これにより、ジェネレーターのライフサイクルを通じて生成された値だけでなく、その最終的な結果も安全に把握できるようになります。

構文(syntax)


1<?php
2function myGenerator() {
3    yield 1;
4    yield 2;
5    return 'Generator finished its work';
6}
7
8$generator = myGenerator();
9
10// ジェネレータを最後まで実行する
11foreach ($generator as $value) {
12    // ここで $value を使用できますが、getReturnのためにはジェネレータが終了している必要があります
13}
14
15// ジェネレータのreturnステートメントによって返された値を取得する
16$returnValue = $generator->getReturn();
17
18// 取得した値を表示する
19echo $returnValue;

引数(parameters)

引数なし

引数はありません

戻り値(return)

mixed

Generator::getReturn() メソッドは、ジェネレータが return ステートメントによって値を返した場合、その値を返します。ジェネレータが return ステートメントで値を返さなかった場合、またはまだ return ステートメントが実行されていない場合は、null を返します。

サンプルコード

PHP Generator getReturn() で終了値を取得する


1<?php
2
3/**
4 * 1から3までの数値を順に生成し、最後にその合計値を返すジェネレータ関数。
5 *
6 * @return \Generator
7 */
8function numberSequenceGenerator(): \Generator
9{
10    $total = 0;
11    for ($i = 1; $i <= 3; $i++) {
12        // yieldキーワードは、ジェネレータの実行を一時停止し、値を呼び出し元に返す。
13        yield $i;
14        $total += $i;
15    }
16
17    // ジェネレータがすべての値をyieldし終えた後、return文で最終的な値を返すことができる。
18    // この値が getReturn() メソッドで取得される。
19    return $total;
20}
21
22// ジェネレータオブジェクトを生成する。この時点では関数の中身は実行されない。
23$generator = numberSequenceGenerator();
24
25// foreachループでジェネレータを反復処理する。
26// このループが完了すると、ジェネレータ関数は最後まで実行され、return文に到達する。
27foreach ($generator as $number) {
28    echo "yieldされた値: {$number}" . PHP_EOL;
29}
30
31// ジェネレータの実行が完了した後、getReturn()メソッドでreturn文の戻り値を取得する。
32// このジェネレータは 1 + 2 + 3 の合計である 6 を返す。
33$returnValue = $generator->getReturn();
34
35echo "ジェネレータの戻り値 (getReturn()で取得): {$returnValue}" . PHP_EOL;
36
37?>

PHPのGenerator::getReturn()メソッドは、ジェネレータ関数が処理を完了した後に、return文で指定された値を取得するために使用します。このメソッドは引数を必要としません。

ジェネレータは、yieldキーワードを使って値を一つずつ生成します。サンプルコードのnumberSequenceGenerator関数では、foreachループによって1から3までの数値が順にyieldされます。このループが完了し、ジェネレータがすべての値を生成し終えると、関数内の処理が最後まで進み、return $total;が実行されます。

重要なのは、getReturn()はジェネレータの反復処理が完全に終了した後に呼び出す必要があるという点です。foreachループの完了後、$generator->getReturn()を実行することで、ジェネレータ関数からreturnされた合計値「6」を取得できます。もしジェネレータの実行が完了する前にこのメソッドを呼び出すと、例外が発生します。

戻り値の型はmixedであり、ジェネレータが返す値の型に依存します。ジェネレータ関数に明示的なreturn文がない場合、getReturn()はnullを返します。

Generator::getReturn()メソッドを使う際の最も重要な注意点は、呼び出すタイミングです。このメソッドは、ジェネレータが値をすべて生成し終わり、処理が完了した後に呼び出す必要があります。サンプルコードのようにforeachループなどでジェネレータを最後まで実行した後に呼び出してください。もし、ジェネレータの処理が完了する前にgetReturn()を呼び出すと、エラー（Exception）が発生しプログラムが停止する原因となります。また、ジェネレータ関数内にreturn文がない場合、このメソッドはnullを返します。意図した値を取得するためには、関数内で明示的に値をreturnするようにしてください。