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

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

作成日: 2025年09月11日更新日: 2025年12月15日

基本的な使い方

getTraceメソッドは、例外がスローされた時点までのプログラムの実行経路、すなわちバックトレース（関数の呼び出し履歴）を取得する処理を実行するメソッドです。JsonExceptionクラスは、PHPの基本的な例外クラスであるExceptionを継承しているため、このメソッドを利用することができます。このメソッドが返す値は配列であり、配列の各要素が、例外発生地点に至るまでの一つ一つの関数呼び出しを表す連想配列になっています。それぞれの連想配列には、呼び出し元のファイル名を示す 'file' キー、行番号を示す 'line' キー、そして呼び出された関数名やメソッド名を示す 'function' キーなどが含まれています。例えば、json_decode関数でエラーが発生してJsonExceptionがスローされた場合、getTraceメソッドを使用することで、どのファイルのどの行でjson_decodeが呼び出され、さらにその呼び出しに至るまでにどのような関数を経由したのかを詳細に追跡することが可能です。この情報は、エラーの原因を特定し、プログラムを修正するデバッグ作業において極めて重要な役割を果たします。

構文(syntax)


1<?php
2$invalidJson = '{"key": "value",}';
3
4try {
5    json_decode($invalidJson, flags: JSON_THROW_ON_ERROR);
6} catch (JsonException $e) {
7    $trace = $e->getTrace();
8    print_r($trace);
9}
10?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

array

このメソッドは、例外発生時のコールスタック（処理の履歴）を配列形式で返します。

サンプルコード

PHP JsonException getTraceAsStringでトレース取得


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()が返したスタックトレース文字列を画面に出力します。

json_decode関数でJsonExceptionを発生させるには、第4引数にJSON_THROW_ON_ERRORの指定が必須です。この指定がない場合、例外は発生せず、デコードに失敗するとnullが返されるため注意が必要です。getTraceAsString()メソッドは、エラー発生までの処理の呼び出し履歴を文字列で取得でき、デバッグ時に原因を特定するのに非常に役立ちます。しかし、この出力にはサーバー内のファイルパスといった機密情報が含まれることがあるため、そのままユーザー画面に表示してはいけません。本番環境ではエラーログへの記録などに留め、開発者のみが内容を確認できるようにすることがセキュリティ上推奨されます。