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

Copy
1<?php
2
3/**
4 * このクラスは、RangeExceptionが発生した際のスタックトレースの取得方法を示します。
5 * 特に、人間が読みやすい文字列として取得する getTraceAsString() の使用例です。
6 */
7class ExceptionTraceExample
8{
9    /**
10     * 処理を実行し、例外を捕捉してスタックトレースを表示します。
11     */
12    public function execute(): void
13    {
14        try {
15            // スタックトレースが生成されるように、メソッドを複数回呼び出します。
16            $this->processValue(200);
17        } catch (RangeException $e) {
18            echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL . PHP_EOL;
19
20            // getTraceAsString()メソッドは、例外発生地点までのコールスタックを
21            // 整形された文字列として返します。ログ出力やデバッグ表示に便利です。
22            // 内部的には getTrace() が返す配列情報を基に文字列を生成しています。
23            $traceString = $e->getTraceAsString();
24
25            echo "--- getTraceAsString() が返すスタックトレース文字列 ---" . PHP_EOL;
26            echo $traceString;
27        }
28    }
29
30    /**
31     * 渡された値を検証するメソッドを呼び出します。
32     *
33     * @param int $value
34     */
35    private function processValue(int $value): void
36    {
37        $this->validateValueInRange($value);
38    }
39
40    /**
41     * 値が有効範囲内か検証し、範囲外であれば例外をスローします。
42     *
43     * @param int $number
44     * @throws RangeException
45     */
46    private function validateValueInRange(int $number): void
47    {
48        // 値が0から100の範囲にない場合、RangeExceptionをスローします。
49        if ($number < 0 || $number > 100) {
50            throw new RangeException("指定された値 {$number} は有効範囲外です。");
51        }
52    }
53}
54
55// クラスのインスタンスを生成し、処理を実行します。
56(new ExceptionTraceExample())->execute();

このPHPコードは、例外が発生した際のプログラムの実行履歴（スタックトレース）を取得する方法を示しています。スタックトレースは、エラーの原因を特定するための重要な手がかりとなります。

サンプルコードでは、execute、processValue、validateValueInRangeの順にメソッドが呼び出されます。最後のvalidateValueInRangeメソッドで、渡された数値が有効範囲外であるため、RangeExceptionという種類の例外が意図的に発生させられます。

try...catchブロックでこの例外を捕捉し、例外オブジェクトのgetTraceAsString()メソッドを呼び出しています。このメソッドは引数を必要とせず、例外が発生するまでに経由したメソッドの呼び出し履歴を、人間が読みやすい形式の文字列として返します。出力結果には、どのファイルの何行目でどのメソッドが呼び出されたかといった詳細な情報が含まれており、プログラムのどこで問題が起きたのかを正確に追跡するのに役立ちます。この整形された文字列は、ログファイルへの記録やデバッグ時の表示に非常に便利です。