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

Copy
1<?php
2
3/**
4 * 配列データを処理中にエラーが発生した場合にスローされるカスタム例外クラス。
5 * RuntimeExceptionを継承し、エラーに関連する配列を保持します。
6 */
7class InvalidArrayDataException extends \RuntimeException
8{
9    /**
10     * エラーの原因となった配列データ。
11     * @var array<mixed>
12     */
13    private array $errorData;
14
15    /**
16     * コンストラクタ
17     *
18     * @param string $message 例外メッセージ
19     * @param array<mixed> $errorData エラーの原因となった配列
20     * @param int $code 例外コード
21     * @param \Throwable|null $previous 直前の例外
22     */
23    public function __construct(string $message = "", array $errorData = [], int $code = 0, ?\Throwable $previous = null)
24    {
25        // 親クラス(RuntimeException)のコンストラクタを呼び出します。
26        parent::__construct($message, $code, $previous);
27        // エラーデータをプロパティに保存します。
28        $this->errorData = $errorData;
29    }
30
31    /**
32     * 例外オブジェクトが文字列に変換される際に自動的に呼び出されるマジックメソッドです。
33     * 親の__toString()が返す情報に、エラーの原因となった配列データを加えて返します。
34     *
35     * @return string 例外の詳細な文字列表現
36     */
37    public function __toString(): string
38    {
39        // 親クラスの__toString()を呼び出して、基本的な例外情報（メッセージ、ファイル、行番号、スタックトレース）を取得します。
40        $exceptionString = parent::__toString();
41
42        // 保持している配列データを、人間が読みやすいJSON形式の文字列に変換します。
43        $dataString = json_encode($this->errorData, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
44
45        // 基本的な例外情報に、エラーデータの情報を追記して返します。
46        return $exceptionString . "\n\n[Invalid Data]\n" . $dataString;
47    }
48}
49
50// 検証対象のサンプル配列データ
51$userData = [
52    'name' => 'Taro Yamada',
53    'age' => -5, // 不正な値
54    'email' => 'taro.yamada@example.com',
55];
56
57try {
58    // 配列データの内容を検証します。
59    if ($userData['age'] < 0) {
60        // ageが負の値の場合、エラー情報として配列全体を渡して例外をスローします。
61        throw new InvalidArrayDataException('Age cannot be a negative value.', $userData);
62    }
63    // 検証が成功した場合の処理（このサンプルでは実行されません）
64    echo "User data is valid." . PHP_EOL;
65} catch (InvalidArrayDataException $e) {
66    // catchした例外オブジェクトをechoで出力します。
67    // これにより、InvalidArrayDataExceptionクラスに実装した__toString()メソッドが自動的に呼び出されます。
68    echo "An error occurred:\n";
69    echo $e;
70}

このサンプルコードは、PHPの特殊なメソッドである__toStringを使い、例外発生時のエラーメッセージを分かりやすくカスタマイズする方法を示しています。

まず、RuntimeExceptionを継承した独自の例外クラスInvalidArrayDataExceptionを定義しています。このクラスは、通常のエラーメッセージに加えて、エラーの原因となった配列データを保持する機能を持っています。

中心となるのが__toStringメソッドです。このメソッドは引数を取らず、例外オブジェクトがechoなどで文字列として出力される際に自動的に呼び出され、そのオブジェクトを表す文字列(string)を返します。サンプルコードでは、親クラスが生成する基本的な例外情報（エラーメッセージ、ファイル名、行番号など）に、保持している配列データをjson_encode関数で見やすく整形した文字列を追加しています。

try-catchブロックでは、年齢に不正な値を持つ配列を検証し、InvalidArrayDataExceptionをスロー（発生）させています。catchブロックでこの例外オブジェクトをechoすると、カスタマイズされた__toStringメソッドが実行されます。結果として、標準のエラー情報だけでなく、問題のあった配列の具体的な内容も一緒に出力されるため、デバッグが容易になります。

Copy
1<?php
2
3/**
4 * RuntimeExceptionが文字列として扱われる際の動作を示すサンプルクラス
5 *
6 * `RuntimeException` は PHP の組み込み例外クラスです。
7 * このクラスのインスタンスが文字列コンテキスト（例: echo）で使用されると、
8 * __toString() メソッドが自動的に呼び出され、
9 * 例外に関する情報（メッセージ、ファイル名、行番号、スタックトレースなど）を
10 * 整形した文字列として返します。
11 */
12final class ExceptionToStringExample
13{
14    /**
15     * 例外を発生させて捕捉し、その文字列表現を出力します。
16     *
17     * @return void
18     */
19    public static function run(): void
20    {
21        try {
22            // 実行時エラーを意図的に発生させます。
23            throw new RuntimeException('データ処理中にエラーが発生しました。', 500);
24        } catch (RuntimeException $e) {
25            // 例外オブジェクトを echo で出力します。
26            // このとき、内部的に $e->__toString() が呼び出されます。
27            echo "例外情報を文字列として出力します:\n";
28            echo "====================================\n";
29            echo $e;
30            echo "\n====================================\n";
31        }
32    }
33}
34
35// クラスのメソッドを実行します。
36ExceptionToStringExample::run();

このサンプルコードは、PHPのRuntimeExceptionクラスに定義されている__toStringメソッドの動作を示しています。__toStringは「マジックメソッド」と呼ばれる特殊なメソッドの一つです。オブジェクトをechoで出力するなど、文字列として扱う必要がある場面で自動的に呼び出されます。

このメソッドは引数を取りません。戻り値として、例外に関する詳細情報が整形されたstring（文字列）を返します。この文字列には、例外作成時に指定したメッセージ、エラーが発生したファイル名と行番号、そしてどの関数やメソッドがどのような順序で呼び出されたかを示すスタックトレースが含まれます。

サンプルコードでは、tryブロックでRuntimeExceptionを意図的に発生させています。catchブロックでその例外オブジェクト$eを捕捉し、echo $e;によって出力しようとしています。このとき、$eを文字列として扱う必要があるため、内部で自動的に$e->__toString()が呼び出されます。その結果、メソッドが返した例外の詳細情報が文字列として画面に表示される仕組みになっています。