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

Copy
1<?php
2
3/**
4 * PHP 8 で JsonException を発生させ、そのスタックトレース情報を取得・表示するサンプルコードです。
5 *
6 * JsonException は、json_decode() や json_encode() 関数で JSON 関連のエラーが発生した際に、
7 * JSON_THROW_ON_ERROR フラグが指定されている場合にスローされます。
8 *
9 * この関数は、与えられた JSON 文字列をデコードしようとします。
10 * 不正な JSON の場合、JsonException を捕捉し、例外の情報を表示します。
11 *
12 * @param string $jsonString 処理するJSON文字列
13 */
14function processJson(string $jsonString): void
15{
16    echo "--- 処理対象のJSON: '{$jsonString}' ---\n";
17    try {
18        // json_decode() を使用して JSON 文字列を PHP の配列またはオブジェクトに変換します。
19        // JSON_THROW_ON_ERROR フラグを指定することで、不正な JSON の場合に
20        // JsonException をスローさせることができます。
21        $data = json_decode($jsonString, true, 512, JSON_THROW_ON_ERROR);
22        echo "  ✅ JSONのデコードに成功しました: " . print_r($data, true) . "\n";
23    } catch (JsonException $e) {
24        // JsonException を捕捉した場合の処理
25        echo "  ❌ JsonException を捕捉しました:\n";
26        echo "    メッセージ: " . $e->getMessage() . "\n"; // 例外のエラーメッセージ
27        echo "    コード: " . $e->getCode() . "\n";     // 例外のエラーコード
28        echo "    ファイル: " . $e->getFile() . "\n";   // 例外が発生したファイル
29        echo "    行番号: " . $e->getLine() . "\n";   // 例外が発生した行番号
30
31        // getTrace() メソッドは、例外発生時のスタックトレース（関数の呼び出し履歴）を
32        // 多次元配列として返します。
33        echo "\n  --- スタックトレース (getTrace() の配列形式) ---\n";
34        $traceArray = $e->getTrace();
35
36        // 初心者にも分かりやすいように、スタックトレース配列の各要素から主要な情報を抜き出して表示します。
37        // 各要素は、ファイル、行、関数、クラス、引数などの情報を含む連想配列です。
38        foreach ($traceArray as $index => $trace) {
39            echo "    #" . $index . " ";
40            // クラス名とメソッド名、または関数名を表示
41            if (isset($trace['class'])) {
42                echo $trace['class'] . ($trace['type'] ?? '') . $trace['function'];
43            } elseif (isset($trace['function'])) {
44                echo $trace['function'];
45            }
46            // 呼び出し元のファイルと行番号を表示 (存在する場合)
47            if (isset($trace['file'])) {
48                echo " in " . $trace['file'] . ":" . $trace['line'];
49            }
50            echo "\n";
51            // var_dump($trace); // 各スタックフレームの全詳細を確認したい場合はコメントを外してください
52        }
53        // 配列全体の構造を確認するには var_dump($traceArray); を使用してください。
54
55        // キーワードにもある getTraceAsString() メソッドは、スタックトレースを
56        // 整形された単一の文字列として返します。ログ出力などに便利です。
57        echo "\n  --- スタックトレース (getTraceAsString() の文字列形式) ---\n";
58        echo $e->getTraceAsString() . "\n";
59    }
60    echo "------------------------------------------------\n\n";
61}
62
63// --- 実行例 ---
64
65// 1. 正常なJSONの処理例
66processJson('{"name": "Alice", "age": 30}');
67
68// 2. 不正なJSONの処理例 (閉じ括弧が不足しているためエラー)
69processJson('{"product": "Laptop", "price": 1200');
70
71// 3. もう一つの不正なJSONの処理例 (JSONデータの後に余分な文字があるためエラー)
72processJson('{"city": "Tokyo"} invalid_data');
73
74?>

このPHPサンプルコードは、JsonExceptionの発生とそのスタックトレース情報を取得・表示する方法を示しています。PHP 8で導入されたJsonExceptionは、json_decode()やjson_encode()関数でJSON_THROW_ON_ERRORフラグが指定されている場合に、不正なJSONデータが検出されるとスローされます。

processJson関数は、与えられたJSON文字列をデコードしようと試み、エラーが発生した場合はtry-catchブロックでJsonExceptionを捕捉します。捕捉した例外オブジェクトからは、エラーメッセージや発生ファイル、行番号といった基本情報を取得することができます。

特に$e->getTrace()メソッドは、例外が発生した時点までのスタックトレースと呼ばれる関数の呼び出し履歴を多次元配列として返します。このメソッドに引数はなく、戻り値はarray型です。戻り値の配列には、各呼び出しフレームのファイル、行番号、関数名、クラス名などの詳細情報が含まれ、エラーの原因特定に役立ちます。サンプルコードでは、この配列をループで処理し、呼び出し履歴を段階的に表示しています。

また、関連する$e->getTraceAsString()メソッドは、スタックトレース情報を整形された単一の文字列として返します。これはログ出力などに便利です。このサンプルコードは、正常なJSONと不正なJSONの処理例を通じて、JsonExceptionの挙動と、getTrace()メソッドがいかに問題解決に貢献するかを初心者にも理解しやすいように示しています。

Copy
1<?php
2
3/**
4 * 不正なJSON文字列をデコードしようとした際にスローされるJsonExceptionを捕捉し、
5 * getTraceAsString()メソッドを使ってスタックトレースを出力するサンプル関数。
6 */
7function demonstrateJsonExceptionTraceAsString(): void
8{
9    // シングルクォートはJSONの仕様に反するため、パースエラーを引き起こす
10    $invalidJsonString = "{'name': 'Taro', 'age': 30}";
11
12    try {
13        // JSON_THROW_ON_ERRORフラグを指定すると、エラー時にJsonExceptionがスローされる
14        json_decode($invalidJsonString, true, 512, JSON_THROW_ON_ERROR);
15    } catch (JsonException $e) {
16        // JsonExceptionをキャッチする
17        echo "JSONデコードエラーが発生しました。" . PHP_EOL;
18        echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
19        echo "-------------------------------------" . PHP_EOL;
20        
21        // getTraceAsString()は、例外が発生するまでの関数呼び出しの履歴（スタックトレース）を
22        // 整形された文字列として返す
23        echo "スタックトレース:" . PHP_EOL;
24        echo $e->getTraceAsString();
25    }
26}
27
28// 関数を実行して結果を確認する
29demonstrateJsonExceptionTraceAsString();

このPHPサンプルコードは、不正なJSON文字列をデコードしようとした際に発生するJsonExceptionを捕捉し、その例外のスタックトレースを文字列として出力する例です。

demonstrateJsonExceptionTraceAsString関数内では、まずJSONの仕様に反するシングルクォートを使った無効なJSON文字列を定義します。次にtryブロック内でjson_decode関数をJSON_THROW_ON_ERRORフラグ付きで実行します。このフラグにより、デコードに失敗するとJsonExceptionがスローされます。

catchブロックでスローされたJsonExceptionのインスタンス（変数$e）を捕捉し、$e->getTraceAsString()メソッドを呼び出しています。このメソッドは引数を取らず、例外が発生した地点に至るまでの関数呼び出しの履歴（スタックトレース）を、人間が読みやすいように整形された一つの文字列として返します。この情報は、エラーの原因がコードのどの部分で、どのような経緯で発生したのかを特定するための重要な手がかりとなります。

最終的に、このコードはエラーメッセージと共に、getTraceAsString()が返したスタックトレース文字列を画面に出力します。

Copy
1<?php
2
3/**
4 * JsonException::getTrace() の使用方法を示すサンプルコード。
5 *
6 * 不正な JSON 文字列をデコードしようとすることで JsonException を発生させ、
7 * その例外からスタックトレースを取得して表示します。
8 */
9function demonstrateJsonExceptionTrace(): void
10{
11    // 不正な JSON 文字列を定義。
12    // 末尾のカンマは JSON 規格違反であり、JsonException を引き起こします。
13    $invalidJson = '{ "item": "example", "value": 123, }';
14
15    try {
16        // JSON_THROW_ON_ERROR フラグを使用して json_decode を実行。
17        // これにより、パースエラーが発生した場合に JsonException がスローされます。
18        json_decode($invalidJson, false, 512, JSON_THROW_ON_ERROR);
19        echo "JSON デコードが成功しました。\n"; // ここには到達しません
20    } catch (JsonException $e) {
21        // JsonException をキャッチした場合
22        echo "JsonException をキャッチしました: " . $e->getMessage() . "\n";
23        echo "エラーコード: " . $e->getCode() . "\n";
24
25        // getTrace() メソッドで例外発生時のスタックトレースを取得
26        // これは Throwable クラスから継承されたメソッドです。
27        $trace = $e->getTrace();
28
29        echo "\n--- スタックトレース (JsonException::getTrace() から) ---\n";
30        // 取得したスタックトレース（配列）を表示
31        print_r($trace);
32        echo "--- スタックトレース終了 ---\n";
33    } catch (Throwable $e) {
34        // その他の予期せぬエラーをキャッチ
35        echo "予期せぬエラーをキャッチしました: " . $e->getMessage() . "\n";
36    }
37}
38
39// 関数を実行してデモンストレーションを開始
40demonstrateJsonExceptionTrace();
41
42?>

JsonException::getTrace()メソッドは、PHPでJSONデータのデコード中に構文エラーなどが発生し、JsonExceptionがスローされた際に、そのエラーの詳細な発生経路を追跡するために用いられます。JsonExceptionは、たとえばjson_decode()関数がJSON_THROW_ON_ERRORフラグ付きで不正なJSON文字列を処理しようとした場合に発生する例外です。

このメソッドは、引数を一切とりません。呼び出すと、例外がスローされた時点でのプログラムの実行経路を示す「スタックトレース」と呼ばれる情報が配列形式で戻り値として返されます。この配列には、各関数の呼び出し元のファイル名、行番号、関数名、そしてその関数に渡された引数などの詳細な履歴が含まれています。

サンプルコードでは、末尾にカンマを含む不正なJSON文字列をjson_decode()に渡し、JsonExceptionを意図的に発生させています。catchブロックでこの例外を捕捉した後、$e->getTrace()を呼び出すことで、プログラムがどの関数をどのような順序で呼び出し、最終的にエラーが発生したのかという一連の流れを示す配列を取得し、表示しています。このスタックトレースは、エラーの原因究明やデバッグ作業において非常に有用な情報源となります。なお、getTrace()はThrowableインターフェースで定義されているため、PHPのすべての例外オブジェクトで利用可能です。