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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 数値を検証し、予期しない値の場合は例外メッセージをJavaScriptのアラートボックスで表示します。
7 *
8 * この関数は、指定された数値が有効範囲内（0以上100以下）にあるかを確認します。
9 * 範囲外の場合、UnexpectedValueExceptionをスローします。
10 * スローされた例外はcatchブロックで捕捉され、例外オブジェクトの'message'プロパティの値を
11 * 使って、ブラウザにメッセージボックス（アラート）を表示します。
12 *
13 * @param int $value 検証する数値
14 * @return void
15 */
16function displayValueWithValidation(int $value): void
17{
18    try {
19        // 値が0未満または100より大きい場合、予期しない値として例外をスローします。
20        // このとき、コンストラクタに渡した文字列が'message'プロパティに設定されます。
21        if ($value < 0 || $value > 100) {
22            throw new UnexpectedValueException('エラー: 値は0から100の間でなければなりません。');
23        }
24
25        // 検証が成功した場合のメッセージを画面に出力します。
26        echo "入力された値 '{$value}' は正常です。";
27    } catch (UnexpectedValueException $e) {
28        // tryブロック内でUnexpectedValueExceptionが発生した場合に、このブロックが実行されます。
29        
30        // 例外オブジェクトから'message'プロパティの値を取得します。
31        // getMessage()メソッドは、このプロパティの値を返します。
32        $errorMessage = $e->getMessage();
33
34        // XSS(クロスサイトスクリプティング)脆弱性を防ぐため、メッセージをエスケープします。
35        $escapedMessage = htmlspecialchars($errorMessage, ENT_QUOTES, 'UTF-8');
36
37        // 取得したエラーメッセージをJavaScriptのalert()関数で表示するためのHTMLを生成します。
38        // これにより、ブラウザ上にメッセージボックスが表示されます。
39        echo "<script>alert('{$escapedMessage}');</script>";
40    }
41}
42
43// --- 関数の実行例 ---
44
45// 予期しない値（範囲外）を渡して、メッセージボックスを表示させる例
46// この行を実行すると、ブラウザに「エラー: 値は0から100の間でなければなりません。」というアラートが表示されます。
47displayValueWithValidation(150);
48
49// 正常な値を渡す例
50// こちらの行を有効にすると、「入力された値 '50' は正常です。」と画面に表示されます。
51// displayValueWithValidation(50);
52

このPHPサンプルコードは、与えられた数値が期待される範囲（0から100）にあるかを検証し、範囲外の場合にブラウザへメッセージボックスを表示するものです。

displayValueWithValidation関数は、検証対象の整数を引数$valueとして受け取ります。この関数は特定の値を返さないため、戻り値の型はvoidです。関数内のtryブロックで値のチェックを行い、もし値が0未満または100より大きい場合は、UnexpectedValueExceptionという例外を意図的に発生させます。このとき、コンストラクタに渡した「エラー: 値は0から100の間でなければなりません。」という文字列が、例外オブジェクトのmessageプロパティに保存されます。

例外が発生すると処理はcatchブロックに移り、発生した例外を捕捉します。catchブロック内では、例外オブジェクト（変数$e）のgetMessage()メソッドを呼び出します。このメソッドは、messageプロパティに保存されているエラーメッセージを文字列として返します。最後に、取得したメッセージ文字列をJavaScriptのalert()関数に組み込んでHTMLとして出力することで、ブラウザにエラー内容を伝えるメッセージボックスが表示される仕組みになっています。

Copy
1<?php
2
3/**
4 * メッセージキューをシミュレートし、メッセージを処理するクラス。
5 *
6 * このサンプルでは、メッセージキューから取り出したデータが期待する形式（特定のキーを持つJSON）
7 * でない場合に UnexpectedValueException を使用します。
8 * catchブロックでは、その例外の 'message' プロパティを取得してエラー内容を表示します。
9 */
10class MessageQueueProcessor
11{
12    /**
13     * メッセージキューを模倣するための配列
14     * @var string[]
15     */
16    private array $queue = [];
17
18    /**
19     * メッセージをキューに追加します。
20     *
21     * @param string $message JSON形式の文字列を想定
22     */
23    public function enqueue(string $message): void
24    {
25        $this->queue[] = $message;
26        echo "キューにメッセージを追加しました: {$message}\n";
27    }
28
29    /**
30     * キューが空になるまで全てのメッセージを処理します。
31     */
32    public function processAll(): void
33    {
34        echo "\n--- メッセージ処理開始 ---\n";
35        while (!empty($this->queue)) {
36            // キューの先頭からメッセージを取り出す
37            $message = array_shift($this->queue);
38
39            try {
40                echo "\n処理対象: {$message}\n";
41
42                // メッセージをJSONオブジェクトとしてデコード
43                // 不正なJSONの場合は JsonException がスローされる
44                $decoded = json_decode(
45                    json: $message,
46                    associative: false, // オブジェクトとしてデコード
47                    flags: JSON_THROW_ON_ERROR
48                );
49
50                // デコードされたデータに 'taskId' プロパティが存在するかチェック
51                if (!property_exists($decoded, 'taskId')) {
52                    // 期待しない値（必須プロパティ欠如）のため例外をスロー
53                    throw new UnexpectedValueException(
54                        "メッセージに必須のプロパティ 'taskId' が含まれていません。"
55                    );
56                }
57
58                // 正常に処理された場合
59                echo "成功: タスクID '{$decoded->taskId}' を処理しました。\n";
60
61            } catch (JsonException $e) {
62                // JSONパース失敗も期待しない値の一種として扱う
63                // 元の例外を保持しつつ、より具体的な例外をスロー
64                throw new UnexpectedValueException(
65                    "メッセージが有効なJSON形式ではありません。",
66                    0,
67                    $e
68                );
69            }
70        }
71        echo "\n--- 全てのメッセージ処理完了 ---\n";
72    }
73}
74
75// --- メインの実行コード ---
76
77// プロセッサのインスタンスを作成
78$processor = new MessageQueueProcessor();
79
80// 正常なメッセージと、意図的に不正なメッセージをキューに追加
81$processor->enqueue('{"taskId": "A-101", "payload": "データ1"}');
82$processor->enqueue('this is not a valid json'); // JSONではない文字列
83$processor->enqueue('{"payload": "データ3"}');       // 必須プロパティ 'taskId' がない
84$processor->enqueue('{"taskId": "C-303", "payload": "データ4"}');
85
86try {
87    // キューの全てのメッセージを処理
88    $processor->processAll();
89} catch (UnexpectedValueException $e) {
90    // 期待しない値に関する例外をここでキャッチ
91    // リファレンスで指定された 'message' プロパティの内容を取得して表示
92    echo "\n[エラー発生] 処理を中断しました。\n";
93    echo "理由: " . $e->getMessage() . "\n";
94}

このPHPコードは、メッセージキューの処理を模倣し、不正なデータを受け取った際の例外処理を示すサンプルです。UnexpectedValueExceptionは、プログラムが想定していない形式や種類の値を受け取ったときに発生させるための例外クラスです。

ここで重要なのが、Exceptionクラスから継承されているmessageプロパティです。このプロパティは、例外が発生した具体的な理由を説明する文字列を保持します。サンプルコードのprocessAllメソッド内では、メッセージが有効なJSON形式でなかったり、必須のプロパティtaskIdが含まれていなかったりする場合に、throw new UnexpectedValueException(...)として、エラー内容を説明する文字列を引数に指定して例外を発生させています。

最後のcatchブロックでは、この発生した例外を捕捉し、$e->getMessage()メソッドを使ってmessageプロパティの値を取得しています。getMessage()メソッドはmessageプロパティの値を取得するためのもので、引数はなく、戻り値として例外に設定されたエラーメッセージの文字列（string）を返します。これにより、「メッセージが有効なJSON形式ではありません。」といった具体的なエラー理由を利用者に伝え、処理を安全に中断することが可能になります。