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

Copy
1<?php
2
3/**
4 * 意図的にLengthExceptionを発生させる関数。
5 *
6 * @param string $input 検証する文字列
7 * @throws LengthException 入力文字列が長すぎる場合にスローされます。
8 */
9function simulateLengthViolation(string $input): void
10{
11    $maxLength = 10; // 許容される最大長
12    if (mb_strlen($input) > $maxLength) {
13        // 文字列が最大長を超えた場合にLengthExceptionをスロー
14        throw new LengthException(
15            "入力文字列は最大 {$maxLength} 文字です。現在の長さ: " . mb_strlen($input) . "。入力: '{$input}'"
16        );
17    }
18    echo "入力文字列 '{$input}' (長さ: " . mb_strlen($input) . ") は有効です。\n";
19}
20
21/**
22 * LengthExceptionの処理とgetTrace()メソッドの使用例を示します。
23 * キーワードgetTraceAsString()の利用例も含まれます。
24 */
25function demonstrateLengthExceptionAndTrace(): void
26{
27    echo "--- LengthException とスタックトレースのデモンストレーション ---\n\n";
28
29    try {
30        // 例外が発生する可能性のある関数を呼び出す
31        simulateLengthViolation("これは非常に長い文字列で、エラーを発生させるはずです。");
32
33        // この行は例外が発生した場合、実行されません。
34        simulateLengthViolation("短い文字列");
35
36    } catch (LengthException $e) {
37        // LengthException が捕捉された場合の処理
38        echo "LengthException が捕捉されました:\n";
39        echo "  メッセージ: " . $e->getMessage() . "\n";
40        echo "  ファイル: " . $e->getFile() . " (行: " . $e->getLine() . ")\n";
41
42        // getTrace() メソッドで、例外が発生するまでの関数呼び出し履歴（スタックトレース）を
43        // 配列形式で取得します。この配列には、ファイル名、行番号、関数名、引数など、詳細な情報が含まれます。
44        echo "\n--- getTrace() の出力 (配列形式のスタックトレース) ---\n";
45        print_r($e->getTrace());
46
47        // キーワードに関連する getTraceAsString() メソッドの利用
48        // このメソッドは、スタックトレースを整形済みの文字列として返します。
49        // エラーログへの記録や、デバッグ情報として表示する際に非常に便利です。
50        echo "\n--- getTraceAsString() の出力 (文字列形式のスタックトレース) ---\n";
51        echo $e->getTraceAsString();
52
53    } catch (Throwable $e) {
54        // その他の予期せぬ例外を捕捉する場合
55        echo "予期せぬエラーが発生しました: " . $e->getMessage() . "\n";
56    }
57
58    echo "\n--- デモンストレーション終了 ---\n";
59}
60
61// デモンストレーション関数を実行
62demonstrateLengthExceptionAndTrace();

PHP 8のLengthExceptionクラスに属するgetTrace()メソッドは、プログラムの実行中に例外が発生した際、その例外がどこで、どのような関数の流れを経て発生したかを示す「スタックトレース」と呼ばれる情報を配列形式で取得するためのメソッドです。引数はなく、例外発生時の関数呼び出しの履歴を格納した配列を返します。

このサンプルコードでは、文字列の長さが制限を超えた場合にLengthExceptionを意図的に発生させています。try-catchブロックでこの例外を捕捉した後、getTrace()メソッドを呼び出すことで、例外発生に至るまでのファイル名、行番号、関数名、引数といった詳細な情報を配列として確認できます。これは、問題の原因を特定するデバッグ作業において非常に役立ちます。

また、キーワードgetTraceAsString()メソッドは、getTrace()が返す配列形式の情報を、人間が読みやすい整形済みの文字列として返します。エラーログへの出力や画面にデバッグ情報を表示する際に便利で、getTrace()と合わせて例外発生時の状況把握とデバッグ作業を効率化するために重要な役割を果たします。

Copy
1<?php
2
3/**
4 * ユーザー登録処理を試みる関数。
5 * 内部でパスワードの検証を呼び出します。
6 *
7 * @param string $password
8 * @return void
9 */
10function attemptToRegisterUser(string $password): void
11{
12    // パスワードが特定の要件を満たしているか検証します。
13    validatePasswordLength($password);
14    echo "ユーザー登録が成功しました。" . PHP_EOL;
15}
16
17/**
18 * パスワードの長さを検証する関数。
19 *
20 * @param string $password
21 * @return void
22 * @throws LengthException パスワードが8文字未満の場合
23 */
24function validatePasswordLength(string $password): void
25{
26    // 文字列の長さが要件（8文字以上）を満たさない場合、LengthExceptionをスローします。
27    if (mb_strlen($password) < 8) {
28        throw new LengthException('パスワードは8文字以上である必要があります。');
29    }
30}
31
32// メインの処理
33try {
34    // 短すぎるパスワードでユーザー登録を試み、意図的に例外を発生させます。
35    attemptToRegisterUser('pass');
36} catch (LengthException $e) {
37    // catchブロックでLengthExceptionを捕捉します。
38    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
39    echo "--- スタックトレース ---" . PHP_EOL;
40
41    // getTraceAsString()メソッドを使い、例外が発生するまでの関数呼び出し履歴（スタックトレース）を
42    // 整形された文字列として取得し、出力します。
43    // これにより、エラーがどこで、どのようにして発生したのかを追跡できます。
44    echo $e->getTraceAsString();
45}
46

このPHPサンプルコードは、関数の呼び出し中にエラーが発生した際に、その原因を追跡する方法を示しています。ここでは、文字列の長さが不正な場合に用いられる LengthException という例外を利用します。

コードでは、まず attemptToRegisterUser 関数が短いパスワード（'pass'）で呼び出されます。この関数は内部で validatePasswordLength 関数を呼び出し、パスワードが8文字未満であるため LengthException を意図的に発生（スロー）させます。

例外が発生する可能性のある処理は try ブロックで囲まれており、発生した LengthException は catch ブロックで捕捉されます。これにより、プログラムが停止することなくエラー処理へ移行できます。

catch ブロック内では、捕捉した例外オブジェクト $e の getTraceAsString() メソッドが呼び出されています。このメソッドは引数を取らず、例外が発生するまでの関数の呼び出し履歴（スタックトレース）を、人間が読みやすい文字列として返します。出力されたスタックトレースを見ることで、どのファイルの何行目で、どの関数から呼び出されてエラーに至ったのか、その詳細な経路を正確に把握でき、デバッグ作業に役立ちます。