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

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

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

基本的な使い方

getTraceAsStringメソッドは、JsonExceptionが発生した際に、その例外のスタックトレースを整形された文字列として取得する処理を実行するメソッドです。スタックトレースとは、プログラムが例外の発生地点に至るまでに、どのような関数やメソッドをどのような順番で呼び出してきたかを示す履歴情報のことです。具体的には、どのファイルの何行目でどの関数が呼び出され、次にどの関数が呼び出されたか、といった一連の流れが含まれています。このメソッドを利用することで、json_encode()やjson_decode()といったJSON関連の処理でエラーが発生した際に、その原因がプログラムのどこにあるのかを特定しやすくなります。通常、try-catchブロックでJsonExceptionオブジェクトを捕捉し、デバッグやエラーログの記録のためにこのメソッドを呼び出します。取得した文字列をログファイルに出力したり、開発中に画面へ表示したりすることで、エラーの原因調査を効率的に進めることができます。

構文(syntax)


1<?php
2
3try {
4    // 不正なJSON文字列をデコードしようとすると JsonException がスローされます
5    json_decode("{'invalid'}", flags: JSON_THROW_ON_ERROR);
6} catch (JsonException $e) {
7    // 例外のスタックトレースを文字列として取得し、出力します
8    echo $e->getTraceAsString();
9}

引数(parameters)

引数なし

引数はありません

戻り値(return)

string

このメソッドは、例外発生時のコールスタック情報を文字列として返します。

サンプルコード

JsonExceptionのgetTraceAsStringでスタックトレースを取得する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * 意図的に深い呼び出し階層を作るための関数
7 *
8 * @param string $data JSON文字列
9 * @return void
10 */
11function processData(string $data): void
12{
13    // 次の関数を呼び出し、例外を発生させる
14    decodeJsonString($data);
15}
16
17/**
18 * JSON文字列をデコードする関数
19 *
20 * @param string $jsonString デコード対象のJSON文字列
21 * @return array デコードされたデータ
22 * @throws JsonException JSONの形式が不正な場合にスローされる
23 */
24function decodeJsonString(string $jsonString): array
25{
26    // JSON_THROW_ON_ERROR フラグを指定することで、
27    // デコード失敗時に JsonException がスローされる
28    return json_decode($jsonString, true, 512, JSON_THROW_ON_ERROR);
29}
30
31// メインの処理
32try {
33    // 意図的に不正な形式のJSON文字列を用意する（末尾にカンマがある）
34    $invalidJson = '{"name": "Taro", "age": 30,}';
35
36    // JSON処理を開始する
37    processData($invalidJson);
38
39} catch (JsonException $e) {
40    // JsonExceptionをキャッチする
41    echo "エラーが発生しました。\n";
42    echo "メッセージ: " . $e->getMessage() . "\n\n";
43
44    // getTraceAsString() を使ってスタックトレースを文字列として取得し、表示する
45    // これにより、例外が発生するまでの関数の呼び出し履歴（どこで、どの関数が呼ばれたか）がわかる
46    echo "--- スタックトレース ---\n";
47    echo $e->getTraceAsString();
48}

JsonExceptionクラスのgetTraceAsString()メソッドは、JSON関連のエラーが発生した時点までのプログラムの実行経路（スタックトレース）を、整形された文字列として取得するためのものです。このメソッドは引数を必要としません。戻り値として、関数の呼び出し履歴が記録された文字列(string)を返します。

サンプルコードでは、まずjson_decode関数で意図的に不正な形式のJSON文字列を処理し、JsonExceptionを発生させています。try...catch構文によってこの例外を捕捉し、catchブロック内で$e->getTraceAsString()を呼び出しています。

その結果、例外が発生するまでにどのファイルのどの行で、どの関数がどのような順序で呼び出されたか、という詳細な情報が文字列として出力されます。この情報は、エラーの原因がどこにあるのかを特定する際の強力な手がかりとなり、プログラムの問題解決（デバッグ）を効率的に進めるために非常に役立ちます。

getTraceAsString()メソッドは、例外が発生するまでの関数の呼び出し履歴（スタックトレース）を文字列で取得できます。これにより、エラーの原因箇所を特定しやすくなるため、開発時のデバッグに非常に役立ちます。ただし、スタックトレースにはファイルパスや関数名といったシステムの内部情報が含まれるため、これを本番環境でユーザーに直接表示することはセキュリティリスクとなります。本番環境では、この情報はログファイルに記録し、ユーザーには「エラーが発生しました」のような一般的なメッセージを表示するのが安全な使い方です。また、このJsonExceptionはjson_decode関数でJSON_THROW_ON_ERRORオプションが指定された場合にのみ発生します。