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

Copy
1<?php
2
3// このコードは、PHPで例外（Exception）が発生した際に、
4// その実行履歴（スタックトレース）を取得する方法を示しています。
5// DomainException は、値が期待される範囲やドメインに属さない場合にスローされる標準例外です。
6
7// 例外が発生する可能性のある処理は 'try' ブロックで囲みます。
8try {
9    echo "--- 処理を開始します ---" . PHP_EOL;
10
11    // ここで意図的に DomainException をスローして、例外処理をシミュレートします。
12    // 例えば、ユーザーからの入力値が特定の範囲外である状況を想定します。
13    $userInput = 150; // 0から100の範囲を期待していると仮定
14    if ($userInput < 0 || $userInput > 100) {
15        // 条件が満たされないため、DomainException をスローします。
16        throw new DomainException("入力値は0から100の範囲でなければなりません。現在の値: " . $userInput);
17    }
18
19    echo "--- 処理が正常に完了しました ---" . PHP_EOL; // この行は例外がスローされるため実行されません
20
21} catch (DomainException $e) {
22    // 'try' ブロック内で DomainException がスローされると、この 'catch' ブロックが実行されます。
23
24    echo "--- DomainException を捕捉しました ---" . PHP_EOL;
25    echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
26    echo "エラー発生ファイル: " . $e->getFile() . PHP_EOL;
27    echo "エラー発生行: " . $e->getLine() . PHP_EOL;
28
29    // getTrace() メソッドは、例外がスローされた時点のコールスタック（関数呼び出しの履歴）を
30    // 配列（array）として返します。これにより、問題がどこで発生したかを詳細に確認できます。
31    $trace = $e->getTrace();
32
33    echo PHP_EOL . "--- スタックトレース (getTrace() の出力) ---" . PHP_EOL;
34    // 配列形式で返されるトレース情報を、print_r を使って見やすく表示します。
35    // 各要素は、呼び出された関数やメソッド、その引数などの情報を含みます。
36    print_r($trace);
37
38    // 参考: getTraceAsString() メソッドを使用すると、整形された文字列として
39    // スタックトレースを取得することもできます。
40    // echo PHP_EOL . "--- getTraceAsString() の出力 ---" . PHP_EOL;
41    // echo $e->getTraceAsString() . PHP_EOL;
42
43} catch (Exception $e) {
44    // DomainException 以外の、他の種類の例外を捕捉したい場合にこのブロックを使用します。
45    echo "--- 予期せぬ例外を捕捉しました ---" . PHP_EOL;
46    echo "エラーメッセージ: " . $e->getMessage() . PHP_EOL;
47}
48
49echo "--- スクリプトの実行が終了しました ---" . PHP_EOL;
50
51?>

PHPでは、プログラム実行中に予期せぬ問題が発生した際に「例外（Exception）」をスローしてエラーを通知します。DomainExceptionは、値が期待される範囲やドメインに属さない場合に用いられる標準例外の一つです。

このサンプルコードは、意図的にDomainExceptionを発生させ、それをtry-catchブロックで捕捉する処理を示しています。捕捉した例外オブジェクト（$e）からgetTrace()メソッドを呼び出すことで、例外がスローされた時点の関数やメソッドの呼び出し履歴（スタックトレース）を詳細に取得できます。

getTrace()メソッドは引数を取りません。戻り値は配列（array）であり、各要素にはファイル名、行番号、呼び出された関数名、引数などの情報が含まれています。これにより、エラーがプログラムのどの部分、どのような流れで発生したのかを具体的に把握することが可能です。

取得したスタックトレースは、print_r()などで表示することで、プログラムの問題箇所を特定し、デバッグを行う上で非常に役立ちます。getTrace()は、システム開発におけるトラブルシューティングの強力なツールとなります。

Copy
1<?php
2
3/**
4 * 特定のドメインルールに従って値を検証する関数。
5 * 値が無効な場合は DomainException をスローします。
6 *
7 * @param int $value 検証する整数値
8 * @throws DomainException 引数が無効なドメイン値である場合
9 * @return string 検証済みの値を示す文字列
10 */
11function validateAndProcessValue(int $value): string
12{
13    // ドメインルール: 値は0から100の範囲内である必要があります。
14    if ($value < 0 || $value > 100) {
15        // ドメインの範囲外の値を検出した場合、DomainException をスローします。
16        // これは、期待される値の範囲（ドメイン）から外れたことを示します。
17        throw new DomainException("値 {$value} は0から100の範囲外です。", 1001);
18    }
19
20    return "正常に処理された値: " . $value;
21}
22
23// 例外処理ブロックを開始
24try {
25    // 正常なケース: ドメインルールを満たす値を渡します。
26    echo validateAndProcessValue(50) . "\n\n";
27
28    // 例外が発生するケース: ドメインルールに違反する値を渡します。
29    // ここで DomainException がスローされ、try ブロックの実行は停止し、
30    // 制御は対応する catch ブロックに移ります。
31    echo validateAndProcessValue(150) . "\n";
32
33    // 上の行で例外がスローされるため、この行は実行されません。
34    echo validateAndProcessValue(20) . "\n";
35
36} catch (DomainException $e) {
37    // DomainException を捕捉した場合の処理
38
39    echo "--- DomainException を捕捉しました ---\n";
40    echo "メッセージ: " . $e->getMessage() . "\n"; // 例外メッセージを取得
41    echo "コード: " . $e->getCode() . "\n";     // 例外コードを取得
42    echo "ファイル: " . $e->getFile() . "\n";   // 例外が発生したファイル名を取得
43    echo "行: " . $e->getLine() . "\n\n";       // 例外が発生した行番号を取得
44
45    echo "--- getTrace() の出力 (スタックトレースの配列) ---\n";
46    // getTrace() メソッドは、例外が発生した時点までの関数呼び出し履歴（スタックトレース）を
47    // 配列形式で返します。この配列には、各呼び出し（フレーム）の詳細情報（ファイル、行、関数名、クラス名、引数など）が含まれます。
48    // デバッグ時に、例外に至るまでのコードの実行パスを理解するのに役立ちます。
49    print_r($e->getTrace());
50    echo "\n";
51
52    echo "--- getTraceAsString() の出力 (スタックトレースの整形された文字列) ---\n";
53    // getTraceAsString() メソッドは、getTrace() で得られるのと同じスタックトレース情報を、
54    // 人間が読みやすいように整形された文字列形式で返します。
55    // 通常、エラーログへの記録や画面表示によく利用されます。
56    echo $e->getTraceAsString();
57    echo "\n";
58
59} catch (Exception $e) {
60    // その他の予期せぬ一般的な例外を捕捉する場合
61    echo "--- 予期せぬ例外を捕捉しました ---\n";
62    echo "メッセージ: " . $e->getMessage() . "\n";
63}
64

PHPの例外処理において、DomainExceptionは特定のドメインルール（期待される値の範囲など）に違反した場合にスローされる例外です。この例外が発生した際、何が原因で、どのコードパスを辿って例外に至ったのかを知ることは、問題解決に非常に役立ちます。

DomainExceptionクラスに属するgetTrace()メソッドは、引数なしで呼び出すと、例外がスローされた時点までのプログラムの実行履歴、すなわち「スタックトレース」を配列として返します。この配列には、各関数呼び出し（フレーム）の詳細情報として、ファイル名、行番号、呼び出された関数名やクラス名、さらにはその関数に渡された引数などが含まれます。開発者はこの情報をデバッグ時に利用し、例外発生に至るまでのコードの実行フローを正確に追跡することができます。

一方、getTraceAsString()メソッドは、getTrace()が提供するのと同じスタックトレース情報を、人間が読みやすいように整形された単一の文字列として返します。通常、このメソッドの出力は、エラーログファイルへの記録や、ユーザーへの簡潔なエラー表示に利用されます。

サンプルコードでは、validateAndProcessValue関数が不正な値を受け取った際にDomainExceptionをスローし、catchブロックでその例外を捕捉しています。捕捉された例外オブジェクトに対してgetTrace()とgetTraceAsString()を呼び出し、それぞれの出力形式の違いと内容を確認できます。これにより、エラー発生時の詳細な状況を把握し、効率的なデバッグに繋げることが可能です。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * ユーザー登録処理を行うクラス
7 */
8class UserRegistration
9{
10    /**
11     * ユーザー名の長さを検証する
12     *
13     * @param string $username 検証するユーザー名
14     * @throws DomainException ユーザー名が規定の文字数範囲外の場合
15     */
16    private function validateUsername(string $username): void
17    {
18        $length = mb_strlen($username);
19        // ユーザー名の長さが3文字未満か20文字より長い場合は、有効な範囲（ドメイン）外とする
20        if ($length < 3 || $length > 20) {
21            // 値が期待されるドメインにないことを示す DomainException をスローする
22            throw new DomainException("ユーザー名「{$username}」は文字数制限を満たしていません。");
23        }
24    }
25
26    /**
27     * ユーザーを登録する
28     *
29     * @param string $username 登録するユーザー名
30     */
31    public function register(string $username): void
32    {
33        echo "ユーザー登録を開始します...\n";
34        // 登録前にユーザー名を検証する
35        $this->validateUsername($username);
36        echo "ユーザー「{$username}」の登録が完了しました。\n"; // 例外が発生するとこの行は実行されない
37    }
38}
39
40// メインの処理
41try {
42    $registration = new UserRegistration();
43    // わざと例外が発生する無効なユーザー名（短すぎる）で登録処理を呼び出す
44    $registration->register("NG");
45} catch (DomainException $e) {
46    // DomainException が発生した場合に、ここで捕捉する
47    echo "----------------------------------------\n";
48    echo "エラーが発生しました: " . $e->getMessage() . "\n\n";
49
50    // getTraceAsString()メソッドは、例外が発生した箇所から、
51    // どの関数やメソッドがどのような順序で呼び出されたか（スタックトレース）を
52    // 整形された文字列として返します。
53    // これにより、エラーの原因調査が容易になります。
54    echo "スタックトレース:\n";
55    echo $e->getTraceAsString();
56    echo "\n----------------------------------------\n";
57}

このPHPコードは、意図的にDomainExceptionという種類の例外を発生させ、catchブロックでその例外オブジェクトが持つgetTraceAsString()メソッドを利用する例を示しています。

getTraceAsString()メソッドは、例外が発生した時点までのプログラムの実行経路、すなわち「スタックトレース」を、人間が読みやすい形式の文字列として取得するために使用します。スタックトレースには、どのファイルの何行目で、どの関数やメソッドが、どのような順序で呼び出されたかといった詳細な情報が含まれています。このメソッドは引数を必要とせず、戻り値として整形されたスタックトレースの文字列を返します。

サンプルコードでは、まずUserRegistrationクラスのregisterメソッドが呼び出されます。その内部でvalidateUsernameメソッドが実行され、ユーザー名が規定の文字数に満たないためDomainExceptionがスローされます。try...catch構文によってこの例外が捕捉され、catchブロック内で$e->getTraceAsString()が実行されます。これにより、例外発生に至るまでのメソッド呼び出しの履歴（registerからvalidateUsernameへ）が出力され、エラーの原因調査を助けます。このように、getTraceAsString()はデバッグ作業において非常に有用なメソッドです。