【PHP8.x】Generator::throw()メソッドの使い方

Copy
1<?php
2
3/**
4 * Generator::throw() メソッドのサンプルコード
5 */
6class MyGenerator
7{
8    /**
9     * ジェネレータ関数
10     *
11     * @return Generator
12     */
13    public static function generatorFunction(): Generator
14    {
15        try {
16            yield 1;
17            yield 2;
18            yield 3;
19        } catch (Exception $e) {
20            echo "例外がキャッチされました: " . $e->getMessage() . PHP_EOL;
21            yield 4; // 例外処理後もジェネレータを続行できる
22        }
23    }
24}
25
26// ジェネレータオブジェクトを作成
27$generator = MyGenerator::generatorFunction();
28
29// ジェネレータから値を取得
30echo $generator->current() . PHP_EOL; // 1
31$generator->next();
32
33echo $generator->current() . PHP_EOL; // 2
34$generator->next();
35
36// ジェネレータに例外をスロー
37try {
38    $generator->throw(new Exception("テスト例外"));
39} catch (Exception $e) {
40    echo "外部で例外がキャッチされました: " . $e->getMessage() . PHP_EOL; // 例外が処理されない場合
41}
42
43echo $generator->current() . PHP_EOL; // 4 (例外処理後のyield)
44$generator->next();
45
46// ジェネレータの完了を確認
47var_dump($generator->valid()); // bool(false)

PHP 8における Generator クラスの throw メソッドは、ジェネレータの実行中に例外を発生させるために使用します。引数には Throwable インターフェースを実装した例外オブジェクトを渡します。この例外は、ジェネレータ関数内の try-catch ブロックでキャッチできます。

サンプルコードでは、MyGenerator クラスの generatorFunction がジェネレータ関数として定義されています。この関数は yield を使用して値を生成し、try-catch ブロック内で例外を捕捉します。

$generator->throw(new Exception("テスト例外")) の部分で、ジェネレータ内に Exception がスローされます。ジェネレータ関数内で例外がキャッチされた場合、例外処理後のコードが実行され、yield 4 によって次の値が生成されます。もしジェネレータ関数内で例外がキャッチされなかった場合、throw を呼び出した箇所で例外がキャッチされます。

throw メソッドの戻り値は Generator オブジェクト自身です。このメソッドを使用することで、ジェネレータの処理フローを外部から制御し、特定のエラー状態をシミュレートしたり、ジェネレータの動作を中断させたりすることができます。ジェネレータが完了すると、$generator->valid() は false を返します。

Copy
1<?php
2
3/**
4 * Generator::throw() のサンプルコード
5 */
6class MyGenerator
7{
8    public function generateValues(): Generator
9    {
10        try {
11            yield 1;
12            yield 2;
13            // 例外がスローされると、ここから処理が中断されます。
14            yield 3;
15        } catch (Exception $e) {
16            echo "Caught exception: " . $e->getMessage() . PHP_EOL;
17            yield 'recovered'; // 例外処理後、値をyieldで返すことも可能
18        }
19    }
20}
21
22$generator = (new MyGenerator())->generateValues();
23
24foreach ($generator as $value) {
25    echo "Value: " . $value . PHP_EOL;
26
27    if ($value === 2) {
28        try {
29            // ジェネレータに例外をスローします。
30            $generator->throw(new Exception("Something went wrong!"));
31        } catch (Exception $e) {
32            echo "Caught exception outside generator: " . $e->getMessage() . PHP_EOL;
33        }
34    }
35}
36

Generator::throw() メソッドは、PHP 8のジェネレータオブジェクトに対して例外をスローするために使用されます。このメソッドは、ジェネレータの実行を一時停止している yield 式の位置で、指定された例外 (Throwable インタフェースを実装したオブジェクト) をスローします。

サンプルコードでは、MyGenerator クラス内で generateValues() メソッドがジェネレータを返します。このジェネレータは、yield を使用して値を生成しますが、try-catch ブロック内で囲まれているため、例外が発生した場合に処理できます。

メインの処理では、ジェネレータから値を取得し、$value が 2 の場合に $generator->throw() を呼び出して、ジェネレータ内部に Exception をスローしています。

ジェネレータ内で例外がキャッチされた場合、catch ブロック内の処理が実行され、エラーメッセージが表示された後、yield 'recovered' によって新しい値を生成して処理を継続できます。もしジェネレータ内部で例外がキャッチされなかった場合は、ジェネレータを呼び出している側のスコープで例外がキャッチされます。

Generator::throw() は、ジェネレータの処理中にエラーが発生した場合に、外部からジェネレータの実行を制御し、エラーハンドリングを行うための強力なツールです。戻り値はジェネレータオブジェクト自身です。

Copy
1<?php
2
3/**
4 * このジェネレータ関数は、値を生成しながら途中で例外を捕捉する準備をします。
5 * Generator::throw() メソッドによって外部から注入された例外を内部で処理する方法を示します。
6 */
7function processWithExternalException(): Generator
8{
9    echo "--- ジェネレータ開始 ---\n";
10
11    // 最初の値を生成
12    yield '最初の処理結果';
13
14    // ここでtry-catchブロックを用意し、外部からの例外を待ちます。
15    try {
16        echo "ジェネレータ内部: 例外の注入を待っています...\n";
17        // yield の箇所でジェネレータの実行が一時停止し、
18        // Generator::throw() が呼び出されると、この行に例外がスローされたかのように動作します。
19        yield '二番目の処理結果 (通常は実行されません)';
20        echo "ジェネレータ内部: 例外はスローされませんでした。\n"; // 例外がなければ実行
21    } catch (Throwable $e) {
22        // Generator::throw() によって注入された例外を捕捉します。
23        echo "ジェネレータ内部: 例外を捕捉しました -> " . $e->getMessage() . "\n";
24        // 例外を捕捉した後も、ジェネレータの処理を続行できます。
25        yield '例外捕捉後の処理結果';
26    }
27
28    echo "--- ジェネレータ終了 ---\n";
29}
30
31// ジェネレータのインスタンスを作成
32$generator = processWithExternalException();
33
34// ジェネレータを最初の yield まで実行し、結果を取得
35echo "外部: " . $generator->current() . "\n"; // "最初の処理結果"
36
37// 次の yield まで進める（try ブロックに入る）
38$generator->next(); // "ジェネレータ内部: 例外の注入を待っています..."
39echo "外部: " . $generator->current() . "\n"; // "二番目の処理結果 (通常は実行されません)"
40
41// ここで Generator::throw() を使用して、ジェネレータの内部に例外を注入します。
42// これは、ジェネレータの現在の中断箇所（yield '二番目の処理結果' の箇所）に
43// new Exception(...) をスローするのと同じ効果を持ちます。
44echo "外部: Generator::throw() を使ってジェネレータに例外を注入します。\n";
45try {
46    $generator->throw(new Exception("これは外部から注入された例外です！"));
47} catch (Throwable $e) {
48    // もしジェネレータ内部で例外が捕捉されなかったり、
49    // 再スローされたりした場合は、ここで捕捉されます。
50    echo "外部: ジェネレータから再スローされた例外を捕捉しました -> " . $e->getMessage() . "\n";
51}
52
53// ジェネレータが例外を捕捉した後の処理結果を取得
54echo "外部: " . $generator->current() . "\n"; // "例外捕捉後の処理結果"
55
56// ジェネレータの実行を完了させる
57$generator->next(); // "--- ジェネレータ終了 ---"
58
59// ジェネレータが完全に終了したか確認（有効な要素がもうないことを確認）
60if (!$generator->valid()) {
61    echo "外部: ジェネレータの実行は全て完了しました。\n";
62}

PHP 8のGenerator::throwメソッドは、実行を一時停止しているジェネレータの内部に、外部から任意の例外を注入するための機能です。引数にはThrowableインターフェースを実装した例外オブジェクトを渡し、メソッド自体はジェネレータ自身を返します。

このサンプルコードでは、ジェネレータ関数が値を生成しながら、途中でtry-catchブロックを用意しています。Generator::throw()を呼び出すと、ジェネレータが最後にyieldで一時停止していた箇所に、指定された例外がスローされたかのように動作します。ジェネレータ内部のcatchブロックでその例外を捕捉することで、外部からの例外注入にもかかわらず、ジェネレータの処理を継続させることが可能です。

具体的には、ジェネレータが「ジェネレータ内部: 例外の注入を待っています...」と表示して一時停止している状態で、外部から$generator->throw(new Exception(...));を呼び出しています。これにより、ジェネレータ内部のtryブロック内で例外が捕捉され、「ジェネレータ内部: 例外を捕捉しました」と表示された後、「例外捕捉後の処理結果」を生成し、処理を続行します。もし内部で例外が捕捉されなかった場合は、その例外はジェネレータの外部に再スローされます。この機能により、ジェネレータの外部から内部の処理フローを制御する、高度なエラーハンドリングが可能になります。

Copy
1<?php
2
3/**
4 * ジェネレータ関数。外部から例外が投げ込まれた場合の振る舞いを示す。
5 *
6 * @return Generator
7 */
8function myGenerator(): Generator
9{
10    echo "--- ジェネレータ開始 ---\n";
11    yield 1;
12    yield 2;
13
14    try {
15        echo "ジェネレータ内部: yield 3 を実行しようとしています。\n";
16        // Generator::throw() が呼ばれると、この yield 3 は実行されずに
17        // try ブロックに例外が注入され、catch ブロックへ処理が移ります。
18        yield 3;
19        echo "ジェネレータ内部: yield 3 が正常に実行されました。\n"; // この行は通常到達しない
20    } catch (RuntimeException $e) {
21        // 外部から Generator::throw() で投げ込まれた RuntimeException を捕捉
22        echo "ジェネレータ内部: RuntimeException を捕捉しました: " . $e->getMessage() . "\n";
23        yield "例外処理完了"; // 例外を処理した後、この値を外部に返す
24    } catch (Throwable $e) {
25        // その他の例外を捕捉する一般的なパターン
26        echo "ジェネレータ内部: その他の例外を捕捉しました: " . $e->getMessage() . "\n";
27        yield "例外処理完了 (その他)";
28    }
29
30    yield 4; // 例外が捕捉されれば、ジェネレータの処理は続行される
31    echo "--- ジェネレータ終了 ---\n";
32}
33
34// ジェネレータの使用例
35try {
36    $generator = myGenerator();
37
38    echo "外部: ジェネレータを初期化しました。\n";
39
40    // 最初の値を取得し、ジェネレータを次の yield まで進める
41    echo "外部: 生成値: " . $generator->current() . "\n"; // 1
42    $generator->next();
43
44    // 2番目の値を取得し、ジェネレータを次の yield (yield 3 の try ブロック内) まで進める
45    echo "外部: 生成値: " . $generator->current() . "\n"; // 2
46    $generator->next();
47
48    // ここで Generator::throw() を使ってジェネレータに RuntimeException を注入する
49    echo "外部: Generator::throw() で RuntimeException を注入します。\n";
50    $generator->throw(new RuntimeException("外部からの意図的なエラー"));
51
52    // 例外処理後の値を取得
53    echo "外部: 生成値 (例外処理後): " . $generator->current() . "\n"; // "例外処理完了"
54    $generator->next(); // ジェネレータを次の yield (yield 4) まで進める
55
56    // 最後の値を取得
57    echo "外部: 生成値: " . $generator->current() . "\n"; // 4
58    $generator->next(); // ジェネレータを完了状態にする
59
60    if (!$generator->valid()) {
61        echo "外部: ジェネレータの処理が完了しました。\n";
62    }
63
64} catch (Throwable $e) {
65    // ジェネレータ内部で捕捉されなかった例外はここに到達します。
66    echo "外部: ジェネレータから伝播した例外を捕捉しました: " . $e->getMessage() . "\n";
67}

PHP 8のGenerator::throwメソッドは、ジェネレータの実行を中断している箇所へ、外部から任意の例外オブジェクトを「投げ込む」ために使用されます。引数にはThrowableインターフェースを実装した例外オブジェクト（例: new RuntimeException(...)）を指定し、メソッド自身はジェネレータオブジェクトを返します。

このメソッドが呼び出されると、ジェネレータは中断していたyield式の位置で指定された例外を受け取ります。ジェネレータ内部にtry-catchブロックがあれば、その例外を捕捉し、適切に処理を続けることが可能です。捕捉された場合、ジェネレータは例外処理のロジックを実行し、そこから新しい値をyieldして外部に返すこともできます。例外が捕捉されずにジェネレータの内部で処理されなかった場合は、その例外はジェネレータの呼び出し元に伝播します。

サンプルコードでは、myGeneratorがyield 3を実行しようとする直前で、外部から$generator->throw(new RuntimeException("外部からの意図的なエラー"));を呼び出しています。これにより、yield 3は実行されず、ジェネレータ内部のcatch (RuntimeException $e)ブロックが発動し、"例外処理完了"という値が返されます。例外が処理された後もジェネレータは処理を続行し、最終的にyield 4まで実行される様子が示されています。このように、Generator::throwは、ジェネレータの外部からエラーを注入し、内部で柔軟に処理するための機能です。