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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 指定された値が有効な範囲内にあるかチェックする。
7 *
8 * @param int $value チェックする値
9 * @param int $min 最小値
10 * @param int $max 最大値
11 * @throws RangeException 値が有効範囲外の場合
12 */
13function checkValueInRange(int $value, int $min, int $max): void
14{
15    if ($value < $min || $value > $max) {
16        // 値が範囲外であれば、RangeExceptionをスローする
17        throw new RangeException("値 {$value} は有効範囲 ({$min}-{$max}) 外です。");
18    }
19}
20
21/**
22 * ユーザーの年齢を検証する処理を実行する。
23 * この関数は checkValueInRange を呼び出す。
24 *
25 * @param int $age 検証する年齢
26 */
27function processUserAge(int $age): void
28{
29    echo "年齢 {$age} を検証します..." . PHP_EOL;
30    checkValueInRange($age, 0, 120); // 年齢の有効範囲を0歳から120歳とする
31    echo "年齢 {$age} は有効です。" . PHP_EOL;
32}
33
34// try-catchブロックで例外処理を実装
35try {
36    // 意図的に範囲外の値を渡し、例外を発生させる
37    processUserAge(150);
38} catch (RangeException $e) {
39    // 発生したRangeExceptionをキャッチする
40    echo "--- エラーが発生しました ---" . PHP_EOL;
41    echo "メッセージ: " . $e->getMessage() . PHP_EOL . PHP_EOL;
42
43    // getTraceAsString()メソッドを呼び出し、
44    // 例外発生地点までのコールスタック（関数の呼び出し履歴）を文字列で取得・表示する。
45    // デバッグ時に、どこで、どのような経緯でエラーが起きたかを追跡するのに役立つ。
46    echo "--- スタックトレース ---" . PHP_EOL;
47    echo $e->getTraceAsString();
48    echo PHP_EOL;
49}

RangeExceptionクラスのgetTraceAsString()メソッドは、例外が発生した地点までのプログラムの呼び出し履歴（スタックトレース）を、人間が読みやすい文字列として取得するためのものです。プログラムのどこで、どのような順序で関数が呼び出されてエラーに至ったのかを特定するデバッグ作業で非常に役立ちます。このメソッドは引数を取らず、戻り値としてスタックトレース情報を含む文字列を返します。

サンプルコードでは、processUserAge関数がcheckValueInRange関数を呼び出します。checkValueInRange関数内で、渡された値が指定範囲外であるためRangeExceptionが発生します。try...catch構文によってこの例外が捕捉されると、catchブロック内で$e->getTraceAsString()が実行されます。これにより、どのファイルの何行目からprocessUserAge関数が呼び出され、次にどのファイルの何行目でcheckValueInRange関数が呼び出されて例外が発生したか、という一連の流れが文字列として表示されます。この出力結果を見ることで、エラーの原因を効率的に追跡できます。