【PHP8.x】ClosedGeneratorException::messageプロパティの使い方

Copy
1<?php
2
3/**
4 * MessagePack の基本的なエンコードとデコード処理を示すクラス。
5 *
6 * このサンプルを実行するには、PHPのMessagePack拡張機能が必要です。
7 * (例: `pecl install msgpack`)
8 *
9 * MessagePackは、JSONのように構造化されたデータをシリアライズするための
10 * 高速でコンパクトなバイナリ形式です。
11 */
12class MessagePackExample
13{
14    /**
15     * データを受け取り、MessagePackでのエンコードとデコードを実行して結果を表示します。
16     *
17     * @param array<string, mixed> $data シリアライズする連想配列
18     * @return void
19     */
20    public function run(array $data): void
21    {
22        echo "--- 元のデータ ---\n";
23        print_r($data);
24        echo "\n";
25
26        // データをMessagePack形式のバイナリ文字列にエンコード（パック）します。
27        $packedData = msgpack_pack($data);
28
29        echo "--- MessagePack形式にエンコードされたデータ (16進数表記) ---\n";
30        echo bin2hex($packedData) . "\n\n";
31
32        // エンコードされたバイナリデータをデコード（アンパック）して元のPHPのデータに戻します。
33        try {
34            $unpackedData = msgpack_unpack($packedData);
35            echo "--- デコードされたデータ ---\n";
36            print_r($unpackedData);
37        } catch (Exception $e) {
38            // データが破損しているなど、デコードに失敗した場合に例外がスローされます。
39            // Exceptionクラスが持つ `message` プロパティ（`getMessage()`メソッドで取得）を
40            // 使って、エラーメッセージを表示します。
41            // これは `ClosedGeneratorException` のような特定の例外でも同様に使われます。
42            echo "デコード中にエラーが発生しました。\n";
43            echo "エラーメッセージ: " . $e->getMessage() . "\n";
44        }
45    }
46}
47
48// サンプルデータを作成します。
49$sampleData = [
50    'id'      => 1001,
51    'user'    => 'Taro Yamada',
52    'active'  => true,
53    'tags'    => ['php', 'messagepack', 'example'],
54    'profile' => null,
55];
56
57// クラスのインスタンスを作成し、処理を実行します。
58$example = new MessagePackExample();
59$example->run($sampleData);
60

ClosedGeneratorExceptionクラスが持つmessageプロパティは、発生した例外に関する説明的なメッセージを文字列として保持します。このプロパティは、PHPの基本的なExceptionクラスから継承されているため、ClosedGeneratorExceptionだけでなく、他の多くの種類の例外オブジェクトでも共通して利用できます。

サンプルコードでは、try-catchブロックを使って、MessagePack形式のデータをデコードする際に発生しうるエラーを捕捉しています。デコードに失敗するとExceptionオブジェクトが生成され、catchブロックで受け取られます。このとき、$e->getMessage()メソッドを呼び出すことで、messageプロパティに格納された具体的なエラー内容を取得し、画面に表示しています。

getMessage()メソッドは引数を取らず、戻り値としてエラーメッセージの文字列（string）を返します。このように、プログラムの実行中に予期せぬ問題が発生した際、messageプロパティを参照することで、エラーの原因を特定するための重要な情報を得ることができます。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * MessageFormatterを使用して、ロケールに応じたメッセージを生成します。
7 *
8 * この関数は、PHPのintl拡張機能に含まれるMessageFormatterクラスを使い、
9 * 国際化(i18n)に対応したメッセージフォーマットの方法を示します。
10 * 数値に応じた単数形・複数形の切り替え(pluralization)も行います。
11 *
12 * 注意: このコードを実行するには、PHPのintl拡張機能が有効である必要があります。
13 *
14 * @param string $locale フォーマットに使用するロケール (例: 'ja_JP', 'en_US')。
15 * @param string $userName 挨拶する相手の名前。
16 * @param int $messageCount 未読メッセージの数。
17 * @return string フォーマットされたメッセージ。
18 */
19function createLocalizedWelcomeMessage(string $locale, string $userName, int $messageCount): string
20{
21    // メッセージのテンプレートを定義します。
22    // {name} : 文字列を埋め込むプレースホルダー
23    // {count, plural, ...} : 数値(count)に応じて表示を切り替える構文
24    //   =0{...}   : 0の場合のテキスト
25    //   =1{...}   : 1の場合のテキスト
26    //   other{...}: その他の場合のテキスト (# は数値を表す)
27    $pattern = 'こんにちは、{name}さん。未読メッセージが{count, plural, =0{ありません}=1{1件あります}other{#件あります}}。';
28
29    // 英語ロケール用のテンプレート
30    if ($locale === 'en_US') {
31        $pattern = 'Hello {name}, you have {count, plural, =0{no unread messages}=1{one unread message}other{# unread messages}}.';
32    }
33
34    // パラメータを配列にまとめます。
35    $params = [
36        'name' => $userName,
37        'count' => $messageCount,
38    ];
39
40    // MessageFormatter::formatMessage() は、指定したロケールとパターン、
41    // パラメータを使って静的にメッセージをフォーマットします。
42    $formattedMessage = MessageFormatter::formatMessage($locale, $pattern, $params);
43
44    // フォーマット処理でエラーが発生した場合、エラーメッセージを返します。
45    if ($formattedMessage === false) {
46        return 'Error: ' . intl_get_error_message();
47    }
48
49    return $formattedMessage;
50}
51
52// --- 実行例 ---
53
54// 日本語での表示例
55echo createLocalizedWelcomeMessage('ja_JP', '鈴木', 5) . PHP_EOL;
56echo createLocalizedWelcomeMessage('ja_JP', '佐藤', 1) . PHP_EOL;
57echo createLocalizedWelcomeMessage('ja_JP', '高橋', 0) . PHP_EOL;
58
59echo PHP_EOL;
60
61// 英語での表示例
62echo createLocalizedWelcomeMessage('en_US', 'John', 10) . PHP_EOL;
63echo createLocalizedWelcomeMessage('en_US', 'Jane', 1) . PHP_EOL;
64echo createLocalizedWelcomeMessage('en_US', 'Mike', 0) . PHP_EOL;
65
66?>

このPHPコードは、国際化対応ライブラリであるintl拡張機能のMessageFormatterクラスを利用して、ユーザーの使用言語（ロケール）に合わせたメッセージを動的に生成する方法を示しています。createLocalizedWelcomeMessage関数は、3つの引数を受け取ります。第1引数の$localeは言語と国を指定する文字列（例: 'ja_JP'）、第2引数の$userNameはメッセージに表示する名前、第3引数の$messageCountは未読メッセージの数です。関数の内部では、{name}のようなプレースホルダーを含むメッセージのテンプレートを定義しています。特に{count, plural, ...}という構文は、$messageCountの値が0、1、またはそれ以上の場合に応じて、「ありません」「1件あります」「#件あります」のように、単数形や複数形を適切に切り替えるための機能です。MessageFormatter::formatMessage静的メソッドが、これらのテンプレートと引数で渡された値を組み合わせて、最終的なメッセージ文字列を生成します。戻り値として、このフォーマット済みの文字列が返されます。実行例では、日本語と英語のロケールで、メッセージ数が変わると出力が適切に変化することが確認できます。

Copy
1<?php
2
3/**
4 * 簡易的なメッセージキューからのメッセージを模倣するジェネレータ関数。
5 *
6 * システムエンジニアを目指す初心者の方へ:
7 * ジェネレータは、すべてのデータを一度にメモリにロードするのではなく、
8 * 必要に応じてデータを「生成」し、メモリ効率の良い処理を可能にします。
9 * 例えば、巨大なファイルを行ごとに処理したり、無限のデータストリームを扱ったりする際に有用です。
10 *
11 * @return Generator メッセージを順次生成するジェネレータオブジェクト
12 */
13function createMessageGenerator(): Generator
14{
15    yield 'メッセージ1: データ処理の開始';
16    yield 'メッセージ2: 中間処理の完了';
17    // ジェネレータはここで全てのメッセージを生成し終え、閉じられます。
18    // そのため、これ以上yieldは実行されません。
19}
20
21/**
22 * メッセージキューからメッセージを消費するワーカープロセスを模倣する関数。
23 *
24 * この関数は、ジェネレータが閉じられた後に、誤ってそのジェネレータから
25 * さらに値を取得しようとした場合に発生する ClosedGeneratorException を示します。
26 *
27 * @throws ClosedGeneratorException ジェネレータが閉じられた後にアクセスされた場合
28 */
29function consumeMessagesAndHandleGeneratorClosure(): void
30{
31    echo "--- メッセージ消費処理を開始します ---\n";
32
33    // メッセージを生成するジェネレータを取得
34    $generator = createMessageGenerator();
35
36    // ジェネレータを使ってメッセージを一つずつ消費します
37    echo "正常なメッセージ消費:\n";
38    foreach ($generator as $message) {
39        echo "- " . $message . "\n";
40    }
41
42    echo "\nすべてのメッセージの消費が完了しました。\n";
43    echo "（ジェネレータはここで閉じられた状態になります）\n";
44
45    // 閉じられたジェネレータにアクセスしようとすると、例外が発生します。
46    // 例えば、current() メソッドで現在の値を取得しようとした場合など。
47    try {
48        echo "\n--- 閉じられたジェネレータにアクセスを試みます ---\n";
49        $generator->current(); // ここで ClosedGeneratorException が発生します
50        echo "この行は実行されません。\n"; // 例外が発生すると、処理は catch ブロックに移ります
51    } catch (ClosedGeneratorException $e) {
52        // ClosedGeneratorException を捕捉し、そのメッセージを表示します。
53        // $e->getMessage() は、リファレンス情報の 'message' プロパティに相当し、
54        // 例外が発生した理由を説明する文字列を返します。
55        echo "捕捉された ClosedGeneratorException:\n";
56        echo "  メッセージ: " . $e->getMessage() . "\n";
57        echo "  （これは、ジェネレータが既に閉じられた後に値を取得しようとしたためです。）\n";
58    }
59
60    echo "\n--- メッセージ消費処理が終了しました ---\n";
61}
62
63// 関数を実行して動作を確認します
64consumeMessagesAndHandleGeneratorClosure();

PHPのClosedGeneratorExceptionクラスは、ジェネレータが既に閉じられた（すなわち、これ以上値を生成しない状態になった）後に、そのジェネレータから値を取得しようとした際に発生する例外です。サンプルコードでは、createMessageGenerator関数が全てのメッセージを生成し終えてジェネレータが閉じられた後、誤ってcurrent()メソッドを呼び出した際にこの例外が発生します。

このClosedGeneratorExceptionクラスのmessageプロパティは、発生した例外に関する詳細な説明文を提供する役割を持ちます。これは、例外がなぜ発生したのかを具体的に示す読み取り専用の文字列データです。サンプルコードでは、try-catchブロックでClosedGeneratorExceptionを捕捉した後、$e->getMessage()という形でこのmessageプロパティの値を取り出し、画面に表示しています。これにより、プログラマーはエラーの原因を迅速に理解し、適切な対応を行うことができます。

messageプロパティは引数を持ちません。その戻り値はstring型で、閉じられたジェネレータにアクセスしようとしたことによってエラーが発生した旨を示す具体的なメッセージを返します。この情報は、システム開発におけるデバッグやエラー処理において重要な手がかりとなります。

Copy
1<?php
2
3/**
4 * ClosedGeneratorException クラスの 'message' プロパティの内容を
5 * 取得・表示するサンプルコードです。
6 *
7 * システムエンジニアを目指す初心者向けに、ジェネレータが閉じられた際に発生する
8 * 例外のメッセージ取得方法を、エラーメッセージを「メッセージボックス」として捉えて示します。
9 */
10
11/**
12 * 簡易的なジェネレータ関数を定義します。
13 * このジェネレータは2つの文字列を順に返します。
14 *
15 * @return Generator
16 */
17function simpleMessageBoxGenerator(): Generator
18{
19    yield 'Hello';
20    yield 'World';
21    // ここでジェネレータは全ての要素を生成し終えるため、閉じられた状態になります。
22    // 明示的に 'return;' を記述することも可能ですが、通常は最後の yield で終了します。
23}
24
25echo "--- ジェネレータの通常の操作 ---\n";
26
27// ジェネレータのインスタンスを作成
28$generator = simpleMessageBoxGenerator();
29
30// 最初のデータを取得し、次へ進む
31if ($generator->valid()) {
32    echo "ジェネレータから: " . $generator->current() . "\n"; // "Hello"
33    $generator->next();
34}
35
36// 2番目のデータを取得し、次へ進む
37if ($generator->valid()) {
38    echo "ジェネレータから: " . $generator->current() . "\n"; // "World"
39    $generator->next();
40}
41
42echo "ジェネレータは全てのデータを生成し終え、閉じられた状態になりました。\n";
43
44echo "--- 閉じられたジェネレータへのアクセス試行と例外捕捉 ---\n";
45
46// 既に閉じられたジェネレータに対して、さらに値の取得や次への移動を試みると
47// ClosedGeneratorException が発生します。
48try {
49    // 閉じられたジェネレータの next() メソッドを呼び出す
50    $generator->next();
51    echo "この行は実行されません。\n"; // 例外が発生するため、この行には到達しません
52} catch (ClosedGeneratorException $e) {
53    // ClosedGeneratorException を捕捉し、そのメッセージを表示します。
54    // このメッセージは、システムからの「エラーメッセージボックス」として
55    // 問題の状況を伝える役割を果たします。
56    echo "\nエラーが発生しました！\n";
57    echo "--- エラーメッセージボックス ---\n";
58    echo "メッセージ: " . $e->getMessage() . "\n"; // ClosedGeneratorException::message プロパティの内容
59    echo "-----------------------------\n";
60    echo "（閉じられたジェネレータへの不正なアクセスを検出しました。）\n";
61}
62
63echo "\n--- スクリプトの実行終了 ---\n";

このサンプルコードは、PHPにおいてジェネレータが既に閉じられた状態（全ての値を生成し終えた後）で、さらに操作を試みた場合に発生するClosedGeneratorExceptionクラスのmessageプロパティの利用方法を説明しています。このmessageプロパティは、例外発生時の具体的なエラー内容を文字列（string型）で保持しており、引数は取りません。

コードではまず、simpleMessageBoxGeneratorというジェネレータ関数を定義し、yieldを使って全ての値を順に生成してジェネレータを閉じられた状態にします。その後、既に閉じられたジェネレータに対して再度next()メソッドなどの操作を試みると、ClosedGeneratorExceptionが発生します。

この例外はtry-catchブロックで捕捉されます。捕捉された例外オブジェクト$eに対してgetMessage()メソッドを呼び出すことで、messageプロパティに格納されているエラーメッセージを取得し、画面に表示しています。このエラーメッセージは、ジェネレータが閉じられた後に不正なアクセスが行われた、という問題の原因を正確に伝える役割を果たし、開発者がエラーの状況を理解し、適切な対応を取るための重要な情報となります。