【PHP8.x】traceプロパティの使い方

Copy
1<?php
2
3/**
4 * 意図的に例外を発生させるための最も深い階層の関数
5 */
6function thirdLevelFunction(): void
7{
8    // ここで意図的に例外を発生させます。
9    // この例外が、呼び出し元のスタックトレース情報を持つことになります。
10    throw new Exception("これは意図的に発生させたエラーです。");
11}
12
13/**
14 * secondLevelFunction から thirdLevelFunction を呼び出す中間関数
15 */
16function secondLevelFunction(): void
17{
18    thirdLevelFunction();
19}
20
21/**
22 * firstLevelFunction から secondLevelFunction を呼び出す中間関数
23 */
24function firstLevelFunction(): void
25{
26    secondLevelFunction();
27}
28
29/**
30 * プログラムのエントリポイント
31 * 例外を捕捉し、スタックトレースをログとして出力する処理を実行します。
32 */
33function main(): void
34{
35    echo "--- プログラム開始 ---\n";
36
37    try {
38        // 例外が発生する可能性のある処理を try ブロックに入れます。
39        firstLevelFunction();
40    } catch (Exception $e) {
41        // 例外がスローされた場合、ここで捕捉されます。
42        echo "\n--- 例外発生 ---\n";
43        echo "エラーメッセージ: " . $e->getMessage() . "\n";
44        echo "発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
45        
46        // Exception オブジェクトの getTrace() メソッドを使用して、
47        // 例外発生時点までのコールスタック（トレース情報）を取得します。
48        // これは 'php trace log' の 'trace' に該当する重要な情報です。
49        $trace = $e->getTrace();
50
51        echo "\n--- スタックトレース (ログ出力イメージ) ---\n";
52        if (!empty($trace)) {
53            // 取得したスタックトレースは配列形式です。
54            // 実際のログ出力では、この情報をファイルに整形して書き込むことが多いです。
55            // 初心者にも分かりやすいように、ここでは print_r で配列の内容を直接表示します。
56            print_r($trace);
57        } else {
58            echo "スタックトレースは利用できませんでした。\n";
59        }
60    }
61
62    echo "\n--- プログラム終了 ---\n";
63}
64
65// プログラムを実行します。
66main();
67
68?>

このPHPサンプルコードは、プログラム実行中に発生した例外（エラー）の情報を詳細に把握するための「スタックトレース」の取得と表示方法を示しています。

コードでは、thirdLevelFunctionからfirstLevelFunctionへと順に関数を呼び出し、最も深い階層で意図的にExceptionを発生させています。main関数内のtry-catchブロックでこの例外を捕捉すると、catchブロック内で例外オブジェクト（$e）からエラーメッセージや発生ファイルなどの基本情報を取得します。

特に重要なのは、$e->getTrace()メソッドです。このメソッドは引数を取らず、例外が発生した時点までの関数の呼び出し履歴（コールスタック）を配列形式で返します。この戻り値が「スタックトレース」情報です。配列には、どの関数が、どのファイルや行番号から呼び出されたかといった詳細が含まれており、エラー発生時の原因特定に不可欠な情報となります。

取得したスタックトレースは、通常はログファイルに整形して記録されますが、この例ではprint_rで内容を直接表示し、その構造を分かりやすく示しています。これにより、プログラムがどのような経路をたどって例外に至ったかを把握でき、問題解決のための「php trace log」として活用できる仕組みを学べます。

Copy
1<?php
2
3/**
4 * このコードは、PHPのExceptionクラスが提供するスタックトレース（コードの実行経路）の取得方法を示します。
5 * キーワード「traceroute」は通常ネットワーク経路の診断ツールを指しますが、
6 * PHPのExceptionにおける「trace」は、例外が発生するまでの関数呼び出しの履歴（スタックトレース）を意味します。
7 * これは、問題発生時のコードの実行フローを理解するために非常に重要です。
8 */
9
10/**
11 * 意図的に例外をスローする関数B。
12 * この関数は、スタックトレースの最深部に位置します。
13 *
14 * @throws Exception
15 */
16function functionB(): void
17{
18    // ここで意図的にExceptionをスローします。
19    throw new Exception("これはテスト用の例外メッセージです。");
20}
21
22/**
23 * 関数Bを呼び出す関数A。
24 * functionAがfunctionBを呼び出すため、スタックトレースにfunctionAの情報も含まれます。
25 */
26function functionA(): void
27{
28    functionB(); // functionBを呼び出す
29}
30
31/**
32 * 例外を捕捉し、そのスタックトレースを表示するメインの関数。
33 * システムエンジニアにとって、例外発生時の原因究明にスタックトレースは不可欠です。
34 */
35function demonstrateExceptionTrace(): void
36{
37    echo "--- 例外スタックトレースのデモンストレーション開始 ---\n\n";
38
39    try {
40        // 例外が発生する可能性のある関数を呼び出します。
41        // この呼び出しが、スタックトレースの起点の一つとなります。
42        functionA();
43    } catch (Exception $e) {
44        echo "例外が捕捉されました！\n";
45        echo "メッセージ: " . $e->getMessage() . "\n";
46        echo "発生ファイル: " . $e->getFile() . " (ライン: " . $e->getLine() . ")\n";
47
48        // ExceptionオブジェクトのgetTrace()メソッドを使ってスタックトレースを取得します。
49        // これは、例外が発生するまでの関数呼び出しの履歴を配列として返します。
50        // この配列の各要素は、特定の呼び出しに関する詳細（ファイル、行、関数、クラスなど）を含みます。
51        $trace = $e->getTrace();
52
53        echo "\n--- スタックトレース情報 ---\n";
54        if (is_array($trace) && count($trace) > 0) {
55            foreach ($trace as $i => $step) {
56                echo "#$i ";
57                // ファイルと行情報がある場合
58                if (isset($step['file'])) {
59                    echo $step['file'] . "(" . $step['line'] . "): ";
60                }
61                // クラスとタイプ（::または->）情報がある場合
62                if (isset($step['class'])) {
63                    echo $step['class'] . ($step['type'] ?? '::'); // typeはメソッドの場合に設定される
64                }
65                // 関数名
66                echo ($step['function'] ?? 'unknown_function') . "()\n";
67            }
68        } else {
69            echo "スタックトレース情報はありません。\n";
70        }
71    }
72
73    echo "\n--- デモンストレーション終了 ---\n";
74}
75
76// デモンストレーションを実行します。
77// この実行により、functionA -> functionB の順で呼び出され、
78// functionBで例外がスローされ、最終的にここで捕捉されます。
79demonstrateExceptionTrace();
80

PHPのExceptionクラスにおける「trace」は、コード実行中に例外が発生するまでの関数呼び出しの履歴、すなわち「スタックトレース」を意味します。ネットワーク経路を診断する「traceroute」とは異なり、PHPのスタックトレースはプログラム内部の実行フローを把握するために利用されます。

Exceptionオブジェクトが提供するgetTrace()メソッドは、例外発生時のスタックトレースを取得する際に使用されます。このメソッドは引数を取らず、例外がスローされるまでに経由した関数やメソッドの呼び出しに関する詳細情報を含む配列を返します。戻り値は?array型で、呼び出し履歴がない場合はnullになる可能性もあります。配列の各要素には、呼び出しが行われたファイル名、行番号、関数名、クラス名などが含まれており、これらの情報から例外発生に至るまでの実行経路を追跡できます。

システムエンジニアがプログラムの問題を特定したりデバッグを行う際、このスタックトレースは非常に重要な手掛かりとなります。サンプルコードでは、意図的に例外をスローする複数の関数を準備し、try-catchブロックで例外を捕捉した後にgetTrace()メソッドを使ってスタックトレース情報を取得し、その内容を表示しています。これにより、例外発生の具体的な原因や、どの関数がどの順番で呼び出されたかを把握することができます。