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

Copy
1<?php
2
3// PHP 8 の Random\RandomException クラスの getTrace メソッドの使用例です。
4// このメソッドは、例外が発生した時点でのプログラムの実行経路（スタックトレース）を配列として返します。
5
6/**
7 * Random\RandomException を意図的に発生させ、その getTrace() および getTraceAsString()
8 * メソッドの動作を示す関数です。
9 */
10function demonstrateRandomExceptionTrace(): void
11{
12    echo "--- Random\\RandomException の発生とトレース情報の取得デモンストレーション ---\n\n";
13
14    try {
15        // Random\RandomException を発生させるために、Randomizer クラスのメソッドに不正な引数を与えます。
16        // Randomizer::getInt(min, max) メソッドは、min が max より大きい場合に
17        // Random\RandomException をスローします。
18        $randomizer = new Random\Randomizer();
19        echo "Randomizer::getInt(10, 5) を実行しようとしています... (min > max)\n";
20        $randomizer->getInt(10, 5);
21
22    } catch (Random\RandomException $e) {
23        echo "\n--- Random\\RandomException を捕捉しました ---\n";
24        echo "例外メッセージ: " . $e->getMessage() . "\n";
25        echo "例外発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n\n";
26
27        echo "--- getTrace() の出力 (配列形式のスタックトレース) ---\n";
28        // getTrace() メソッドは、スタックトレース情報を連想配列の配列として返します。
29        // 各要素は、関数呼び出しの情報（ファイル、行、関数名、引数など）を含みます。
30        // 配列の内容を分かりやすく表示するために var_dump を使用します。
31        var_dump($e->getTrace());
32
33        echo "\n--- getTraceAsString() の出力 (文字列形式のスタックトレース) ---\n";
34        // getTraceAsString() メソッドは、スタックトレース情報を整形された文字列として返します。
35        // これは、エラーログに記録する際など、可読性を重視する場合に便利です。
36        echo $e->getTraceAsString() . "\n";
37
38    } catch (Throwable $e) {
39        // Random\RandomException 以外の、予期せぬ例外を捕捉する場合
40        echo "\n--- 予期せぬ例外が発生しました ---\n";
41        echo "例外の種類: " . get_class($e) . "\n";
42        echo "メッセージ: " . $e->getMessage() . "\n";
43    }
44
45    echo "\n--- デモンストレーション終了 ---\n";
46}
47
48// 関数を実行して、Random\RandomException の動作を確認します。
49demonstrateRandomExceptionTrace();

PHP 8 の Random\RandomException::getTrace メソッドは、プログラム実行中に Random\RandomException が発生した際に、その例外がどこで、どのようにして発生したかの詳細な実行経路（スタックトレース）を配列形式で取得するために使用されます。このメソッドは引数を必要とせず、例外発生時点までの関数やメソッドの呼び出し履歴を、ファイル名、行番号、関数名、引数などの情報を含む連想配列の配列として返します。

サンプルコードでは、Randomizer::getInt(10, 5) のように不正な引数を意図的に与えることで Random\RandomException を発生させています。catch ブロック内で $e->getTrace() を呼び出すと、例外が発生した時点までの関数呼び出しの階層が配列として取得され、var_dump でその具体的な内容を確認できます。

この配列形式のスタックトレース情報は、プログラムのデバッグ時に例外の原因を特定したり、エラーの発生経路を分析したりするのに非常に役立ちます。また、関連する getTraceAsString() メソッドは、同じスタックトレース情報を整形された単一の文字列として返すため、エラーログへの出力など、可読性を重視する場面で便利に活用できます。これらのメソッドを適切に使い分けることで、例外処理や問題調査の効率を向上させることが可能です。

Copy
1<?php
2
3/**
4 * 擬似的に乱数処理Aをシミュレートし、次の関数を呼び出します。
5 *
6 * この関数は、スタックトレースに現れるための呼び出しスタックの一部です。
7 */
8function simulateRandomProcessA(): void
9{
10    // 何らかの処理があった後、次の関数を呼び出すと仮定
11    simulateRandomProcessB();
12}
13
14/**
15 * 擬似的に乱数処理Bをシミュレートし、意図的に \Random\RandomException をスローします。
16 *
17 * この関数で例外をスローすることで、そのスタックトレースを捕捉し、
18 * \Random\RandomException::getTrace() メソッドの動作をデモンストレーションします。
19 */
20function simulateRandomProcessB(): void
21{
22    // ここで乱数生成器の内部エラーをシミュレートする状況を仮定
23    throw new \Random\RandomException("擬似的な乱数処理エラーが発生しました。");
24}
25
26/**
27 * \Random\RandomException を捕捉し、そのスタックトレースを文字列形式で表示する関数です。
28 *
29 * この関数は、\Random\RandomException::getTrace() メソッドで取得した配列形式の
30 * スタックトレースを、人間が読みやすい文字列形式に変換して出力します。
31 * (注: Random\RandomException は PHP 8.2 以降で利用可能です。)
32 */
33function demonstrateRandomExceptionTraceAsString(): void
34{
35    try {
36        simulateRandomProcessA();
37    } catch (\Random\RandomException $e) {
38        echo "--- \\Random\\RandomException が捕捉されました ---\n";
39        echo "メッセージ: " . $e->getMessage() . "\n";
40        echo "発生ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n\n";
41
42        echo "--- スタックトレース (文字列形式) ---\n";
43        $trace = $e->getTrace();
44        $traceStrings = [];
45
46        foreach ($trace as $i => $frame) {
47            $class = $frame['class'] ?? '';
48            $type = $frame['type'] ?? ''; // '::' (静的メソッド) または '->' (オブジェクトメソッド)
49            $function = $frame['function'] ?? '<unknown function>';
50            
51            // ファイルと行の情報は、内部関数やeval()されたコードでは存在しない場合がある
52            $file = $frame['file'] ?? '<internal function>';
53            $line = $frame['line'] ?? '';
54
55            // 引数を整形 (初心者向けに型を表示)
56            $argsFormatted = [];
57            if (isset($frame['args']) && is_array($frame['args'])) {
58                foreach ($frame['args'] as $arg) {
59                    $argsFormatted[] = gettype($arg);
60                }
61            }
62
63            // スタックトレースの各行を整形 (PHPの標準出力に似た形式)
64            $traceStrings[] = sprintf(
65                "#%d %s%s%s(%s) called at %s%s",
66                $i,
67                $class,
68                $type,
69                $function,
70                implode(', ', $argsFormatted),
71                $file,
72                ($line !== '') ? (':' . $line) : ''
73            );
74        }
75
76        // スタックトレースの最後に {main} エントリを追加して、PHPの標準的な出力に近づける
77        $traceStrings[] = sprintf(
78            "#%d {main}",
79            count($trace)
80        );
81
82        echo implode("\n", $traceStrings) . "\n";
83    }
84}
85
86// スクリプトの実行を開始
87demonstrateRandomExceptionTraceAsString();

Random\RandomException::getTrace() メソッドは、PHP 8.2以降で利用可能な Random\RandomException クラスに属し、例外が発生した時点までのプログラムの呼び出し履歴（スタックトレース）を取得するために使用されます。引数はなく、例外が発生するまでにどの関数がどの関数を呼び出したかを示す詳細な情報が配列形式で返されます。

このサンプルコードでは、まず simulateRandomProcessA()、simulateRandomProcessB() という関数が順に呼び出され、simulateRandomProcessB() 内で意図的に Random\RandomException がスローされます。demonstrateRandomExceptionTraceAsString() 関数は、この例外を try-catch ブロックで捕捉します。

捕捉された例外オブジェクト $e から $e->getTrace() メソッドを呼び出すことで、スタックトレースが配列として取得されます。この配列には、各呼び出しフレームのファイル名、行番号、クラス名、関数名、引数などの情報が含まれています。サンプルコードでは、この配列の情報を整形し、PHPの標準的なエラー出力に似た人間が読みやすい文字列形式のスタックトレースとして画面に表示しています。これにより、例外発生時のプログラムの流れを詳細に把握し、問題の原因究明に役立てることができます。