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

Copy
1<?php
2
3/**
4 * 意図的に AssertionError を発生させる関数。
5 * この関数内でアサーションが失敗すると、AssertionError がスローされます。
6 *
7 * @param bool $condition アサートする条件
8 */
9function triggerAssertionError(bool $condition): void
10{
11    // assert() 関数は、条件が false の場合に AssertionError をスローします。
12    // PHP 8 では、デフォルトで php.ini の assert.exception が有効です。
13    assert($condition, 'このアサーションは失敗しました！');
14}
15
16try {
17    echo "--- アサーションエラーを発生させます ---" . PHP_EOL;
18    // 条件を false にすることで、AssertionError を意図的にスローします。
19    triggerAssertionError(false);
20    echo "この行は実行されません。" . PHP_EOL; // エラー発生後に実行されない
21} catch (AssertionError $e) {
22    echo "--- AssertionError を捕捉しました ---" . PHP_EOL;
23    echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
24    echo "発生ファイル: " . $e->getFile() . PHP_EOL;
25    echo "発生行番号: " . $e->getLine() . PHP_EOL . PHP_EOL;
26
27    // getTrace() は、スタックトレース情報を配列として返します。
28    // 各配列要素は、呼び出された関数、ファイル、行番号などの詳細情報を含みます。
29    echo "--- getTrace() の出力 (配列形式) ---" . PHP_EOL;
30    print_r($e->getTrace());
31    echo PHP_EOL;
32
33    // getTraceAsString() は、スタックトレース情報を整形された文字列として返します。
34    // これはデバッグログへの出力や、エラー画面での表示に非常に便利です。
35    echo "--- getTraceAsString() の出力 (文字列形式) ---" . PHP_EOL;
36    echo $e->getTraceAsString() . PHP_EOL;
37}
38
39?>

このPHPサンプルコードは、プログラムの想定外の挙動を示すAssertionErrorの発生から捕捉、そしてエラー発生時の呼び出し履歴（スタックトレース）の取得方法を学ぶためのものです。triggerAssertionError関数内でassert()が意図的に失敗することでAssertionErrorがスローされ、try-catchブロックで捕捉されます。

AssertionError::getTrace()メソッドは、この捕捉されたエラーが発生した時点までの関数の呼び出し順序、つまりスタックトレースの情報を配列形式で取得します。このメソッドに引数はなく、各呼び出しの情報（関数名、ファイル名、行番号など）を含む連想配列の要素を持つ配列が戻り値として返されます。これはプログラムがどの関数からどの関数へと実行され、最終的にエラーに至ったかを詳細に分析する際に非常に役立ちます。

また、サンプルコードではgetTraceAsString()メソッドも紹介されています。こちらはgetTrace()が返す配列情報を、人間が読みやすい整形された文字列として出力するため、デバッグログへの記録やエラーメッセージの表示に便利に利用できます。これらのメソッドは、エラー発生時の原因究明やデバッグ作業において重要な役割を果たします。

Copy
1<?php
2
3// assert() 関数が失敗時に AssertionError をスローするように設定します。
4// PHP 8 では assert() のデフォルトの振る舞いが変更され、ASSERT_EXCEPTION を true に設定することで
5// AssertionError がスローされるようになります。
6assert_options(ASSERT_CALLBACK, null);    // 既存のコールバック関数があればクリア
7assert_options(ASSERT_EXCEPTION, true);   // アサーション失敗時に AssertionError をスロー
8
9/**
10 * Assertion Error の発生と、そのトレース情報を取得し文字列として整形するデモンストレーション。
11 *
12 * システムエンジニアを目指す初心者向けに、AssertionError が発生した際の
13 * 呼び出し履歴（スタックトレース）を array 形式で取得し、
14 * 人間が読みやすい文字列として表示する方法を示します。
15 */
16function demonstrateAssertionErrorTrace(): void
17{
18    echo "--- Assertion Error トレース情報取得デモンストレーション ---\n\n";
19
20    try {
21        // わざと失敗するアサーションを実行する関数を呼び出します。
22        // これにより AssertionError が発生します。
23        callFunctionThatAsserts();
24
25    } catch (AssertionError $e) {
26        // AssertionError が発生した場合はここで捕捉されます。
27        echo "AssertionError が捕捉されました:\n";
28        echo "メッセージ: " . $e->getMessage() . "\n\n";
29
30        echo "--- getTrace() メソッドによるトレース情報（配列）の整形出力 ---\n";
31
32        // getTrace() メソッドは、例外が発生した時点のコールスタックを
33        // 連想配列の配列として返します。
34        $trace = $e->getTrace();
35
36        // 取得したトレース配列をループ処理し、各フレームの情報を整形して表示します。
37        // トレースは最も新しい呼び出し（0番）から古い呼び出しへと順に並びます。
38        foreach ($trace as $index => $frame) {
39            echo "#{$index} "; // フレームのインデックス
40
41            // ファイル名と行番号が存在する場合
42            if (isset($frame['file']) && isset($frame['line'])) {
43                echo "{$frame['file']}({$frame['line']}): ";
44            }
45
46            // クラス名、型（:: または ->）、関数名が存在する場合
47            if (isset($frame['class'])) {
48                echo "{$frame['class']}{$frame['type']}";
49            }
50            if (isset($frame['function'])) {
51                echo "{$frame['function']}()";
52            }
53            echo "\n"; // 各フレームの終わりに改行
54        }
55        echo "\n";
56        echo "--------------------------------------------------------\n";
57
58    } catch (Throwable $e) {
59        // AssertionError 以外の予期せぬエラーも捕捉します。
60        echo "予期せぬエラーが捕捉されました: " . get_class($e) . " - " . $e->getMessage() . "\n";
61    }
62}
63
64/**
65 * わざと Assertion Error を発生させるヘルパー関数。
66 * この関数が呼び出されることで、assert(false) が実行され AssertionError がスローされます。
67 */
68function callFunctionThatAsserts(): void
69{
70    // このアサーションは常に失敗し、AssertionError をスローします。
71    assert(false, "このアサーションは、デモンストレーションのために意図的に失敗させました。");
72}
73
74// デモンストレーション関数を実行します。
75demonstrateAssertionErrorTrace();

PHP 8のAssertionErrorクラスに属するgetTrace()メソッドは、プログラムのアサーションが失敗しAssertionErrorがスローされた際に、そのエラーが発生するまでの関数呼び出しの経緯（スタックトレース）を取得するのに利用されます。このメソッドは引数を一切取らず、戻り値として、呼び出し履歴の各ステップに関する詳細情報を含む連想配列の配列を返します。配列の各要素は一つの呼び出しフレームを表し、ファイル名、行番号、クラス名、メソッド名、関数名といった情報が含まれており、エラーの原因特定に不可欠な手掛かりとなります。

サンプルコードでは、assert_options関数を使用して、アサーション失敗時にAssertionErrorがスローされるように環境を設定しています。その後、意図的に失敗するアサーションを実行することでAssertionErrorを発生させ、try-catchブロックでその例外を捕捉しています。捕捉したAssertionErrorオブジェクトに対してgetTrace()メソッドを呼び出すと、エラー発生時の詳細なスタックトレース情報が配列として手に入ります。コードの後半では、この取得した配列を繰り返し処理し、各フレームの情報を抽出しながら、システムエンジニアが読みやすい形式の文字列として表示する手順を示しています。これは、getTrace()が返す生データから、デバッグに役立つ整形されたトレース情報を生成する具体的な方法を初心者向けに解説するものです。