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

getTraceAsStringメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年12月20日

基本的な使い方

getTraceAsStringメソッドは、例外が発生した時点のスタックトレースを文字列として取得する処理を実行するメソッドです。このメソッドは、UnexpectedValueExceptionクラスがPHPの基本的な例外クラスであるExceptionクラスから継承している機能の一つです。スタックトレースとは、プログラムが例外の発生地点に至るまでに、どのファイルのどの行で、どの関数やメソッドがどのような順番で呼び出されたかという一連の実行履歴を指します。この情報には、関数の呼び出し順序、引数、ファイルパス、行番号などが含まれており、デバッグ作業において極めて重要な役割を果たします。例えば、予期しない値が原因でUnexpectedValueExceptionが発生した場合、このメソッドを使うことで、問題の値がどこから渡されてきたのか、その呼び出し経路を遡って調査することができます。返される文字列は人間が読みやすい形式に整形されているため、ログファイルへの記録や、開発中のエラー画面への表示に直接利用することが可能です。これにより、エラーの原因特定を迅速かつ効率的に行うための強力な手段となります。

構文(syntax)


1<?php
2try {
3    throw new UnexpectedValueException("予期しない値が検出されました。");
4} catch (UnexpectedValueException $e) {
5    echo $e->getTraceAsString();
6}
7?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

string

例外発生時のトレース情報を、人間が読める形式の文字列として返します。

サンプルコード

PHP例外のトレース文字列を取得する


1<?php
2
3/**
4 * ユーザーの年齢を検証する関数。
5 *
6 * この関数は、年齢が0以上の整数であることを期待します。
7 * 期待しない型の値が渡された場合、UnexpectedValueExceptionをスローします。
8 *
9 * @param mixed $age 検証対象の年齢
10 * @return void
11 * @throws UnexpectedValueException 年齢が0以上の整数でない場合
12 */
13function validateUserAge(mixed $age): void
14{
15    if (!is_int($age) || $age < 0) {
16        // 期待しない値（この場合は整数以外や負の数）が渡されたため例外をスロー
17        throw new UnexpectedValueException('年齢は0以上の整数でなければなりません。');
18    }
19    echo "年齢の検証に成功しました: {$age}" . PHP_EOL;
20}
21
22/**
23 * ユーザー登録処理を行う関数。
24 *
25 * @param array $userData ユーザーデータ
26 * @return void
27 */
28function registerUser(array $userData): void
29{
30    echo "ユーザー {$userData['name']} の登録処理を開始します..." . PHP_EOL;
31    // 内部で年齢の検証を行う
32    validateUserAge($userData['age']);
33    echo "ユーザー登録が完了しました。" . PHP_EOL;
34}
35
36// メインの処理
37try {
38    // 意図的に不正なデータ（年齢が文字列）を渡して、例外を発生させる
39    $invalidUserData = ['name' => '山田太郎', 'age' => '三十歳'];
40    registerUser($invalidUserData);
41} catch (UnexpectedValueException $e) {
42    // 捕捉した例外の情報を画面に出力する
43    echo "----------------------------------------" . PHP_EOL;
44    echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
45    echo "----------------------------------------" . PHP_EOL;
46    
47    // getTraceAsString()メソッドを使い、例外が発生するまでの
48    // 関数の呼び出し履歴（スタックトレース）を文字列として取得し、表示します。
49    // これにより、どこで問題が起きたのかを追跡できます。
50    echo "スタックトレース:" . PHP_EOL;
51    echo $e->getTraceAsString();
52    echo PHP_EOL;
53    echo "----------------------------------------" . PHP_EOL;
54}

UnexpectedValueException::getTraceAsString()は、例外が発生した地点までのプログラムの実行経路（関数の呼び出し履歴）を、人間が読みやすい文字列形式で取得するためのメソッドです。このメソッドに引数は必要なく、戻り値としてスタックトレース情報を含む文字列を返します。

このサンプルコードでは、ユーザーの年齢を検証するvalidateUserAge関数に対し、意図的に不正なデータ（文字列の '三十歳'）を渡すことでUnexpectedValueExceptionを発生させています。try...catch構文でこの例外を捕捉し、catchブロック内で$e->getTraceAsString()を実行しています。

このメソッドを呼び出すと、例外が発生するまでの関数の呼び出し履歴、つまり「メインの処理からregisterUser関数が呼ばれ、その中でvalidateUserAge関数が呼ばれた結果、例外が発生した」という一連の流れが、ファイル名や行番号とともに文字列として取得・表示されます。この出力結果は「スタックトレース」と呼ばれ、エラーの原因を調査するデバッグ作業で非常に役立ちます。プログラムのどこで、どのような順序で処理が進んだ結果エラーに至ったのかを正確に追跡できるため、問題箇所の特定が容易になります。

getTraceAsString()は、エラー発生箇所を特定するために、どの関数がどの順番で呼び出されたかの履歴（スタックトレース）を文字列として取得するメソッドです。デバッグ時に非常に役立ちます。注意点として、スタックトレースにはファイルパスなどの機密情報が含まれる可能性があるため、開発中の確認にのみ使用し、ユーザーが利用する本番環境の画面には絶対に出力しないでください。本番環境では、エラー情報は利用者の目に見えないログファイルに記録し、画面には「エラーが発生しました」のような一般的なメッセージを表示するのが安全な実装方法です。また、try...catchで例外を捕捉しないとプログラムが強制終了するため、エラーの可能性がある処理は必ず囲むようにしましょう。