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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 内部に配列を保持し、文字列として表現するためのカスタムクラス。
7 *
8 * このクラスのインスタンスが文字列として評価される際、マジックメソッド `__toString()` が呼び出され、
9 * 保持している配列をJSON形式の文字列に変換して返します。
10 */
11class ArrayStringifier
12{
13    /**
14     * @param array<mixed> $data 文字列に変換したい配列
15     */
16    public function __construct(private array $data)
17    {
18    }
19
20    /**
21     * オブジェクトが文字列にキャストされるときに自動的に呼び出されるメソッド。
22     *
23     * @return string 内部の配列をJSON形式にした文字列を返す。
24     */
25    public function __toString(): string
26    {
27        // json_encodeは失敗時にfalseを返す可能性があるため、安全に文字列を返す
28        return json_encode($this->data, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT) ?: '[]';
29    }
30}
31
32/**
33 * 指定された値が配列であるか検証する関数。
34 *
35 * 配列でない場合、UnexpectedValueExceptionをスローします。
36 *
37 * @param mixed $value 検証する値
38 * @return void
39 * @throws UnexpectedValueException 値が配列でない場合にスローされる
40 */
41function processArray(mixed $value): void
42{
43    // 値が配列でない場合は、期待しない値として例外をスローする
44    if (!is_array($value)) {
45        throw new UnexpectedValueException('An array was expected, but received ' . gettype($value));
46    }
47
48    // 値が配列の場合、ArrayStringifierオブジェクトを作成して文字列として出力する
49    $stringifier = new ArrayStringifier($value);
50    echo $stringifier . PHP_EOL; // ここで ArrayStringifier::__toString() が呼び出される
51}
52
53
54// --- 正常な実行例 ---
55echo "--- Success case ---" . PHP_EOL;
56$validArray = ['id' => 123, 'name' => 'PHP User', 'skills' => ['coding', 'debug']];
57processArray($validArray);
58
59echo PHP_EOL;
60
61// --- 例外が発生する例 ---
62echo "--- Exception case ---" . PHP_EOL;
63try {
64    // 配列ではない値（文字列）を関数に渡す
65    processArray('this is not an array');
66} catch (UnexpectedValueException $e) {
67    // 捕捉した例外オブジェクトを文字列として出力する
68    // ここで UnexpectedValueException::__toString() が暗黙的に呼び出される
69    echo "Caught an exception:" . PHP_EOL;
70    echo $e;
71}
72

このPHPサンプルコードは、オブジェクトが文字列として扱われる際に自動的に呼び出されるマジックメソッド__toString()の動作を、特にUnexpectedValueExceptionクラスを例に解説するものです。

__toString()は引数を取らず、必ず文字列(string)を返す必要があります。クラスにこのメソッドを定義すると、そのクラスのインスタンスがecho文などで出力される際の文字列表現を自由にカスタマイズできます。

サンプルコードでは、まずカスタムクラスArrayStringifierで__toString()を実装し、オブジェクトがechoされると保持している配列がJSON形式の文字列に変換される様子を示しています。

次に、processArray関数が配列以外の値を受け取った場合にUnexpectedValueExceptionを発生させます。try...catchブロックでこの例外オブジェクトを捕捉し、echoで出力すると、UnexpectedValueExceptionクラスに定義されている__toString()メソッドが暗黙的に呼び出されます。このメソッドは、例外クラス名、エラーメッセージ、発生したファイル名と行番号、スタックトレースなどの詳細なデバッグ情報を整形された一つの文字列として返します。このように、例外オブジェクトを直接出力するだけで、プログラムのどこでどのような問題が起きたかを簡単に確認することができます。

Copy
1<?php
2
3/**
4 * 数値の配列を検証し、不正な値があれば例外をスローします。
5 *
6 * @param array $numbers 数値の配列
7 * @throws UnexpectedValueException 配列に数値以外の値が含まれている場合
8 */
9function processNumbers(array $numbers): void
10{
11    foreach ($numbers as $index => $number) {
12        if (!is_numeric($number)) {
13            // 期待しない値が見つかったため、UnexpectedValueExceptionをスローする
14            throw new UnexpectedValueException(
15                "Invalid value detected at index {$index}. Expected a number."
16            );
17        }
18        echo "Processing number: {$number}" . PHP_EOL;
19    }
20}
21
22// 検証用のデータ（意図的に不正な値を含める）
23$data = [10, 20, 'thirty', 40];
24
25try {
26    echo "Starting data processing..." . PHP_EOL;
27    processNumbers($data);
28    echo "Data processing finished successfully." . PHP_EOL;
29} catch (UnexpectedValueException $e) {
30    // 例外オブジェクトをechoで出力すると、__toString()メソッドが自動的に呼び出される
31    // これにより、例外に関する整形された情報（メッセージ、ファイル、行番号、スタックトレース）が文字列として得られる
32    echo "----------------------------------------" . PHP_EOL;
33    echo "An error occurred:" . PHP_EOL;
34    echo $e; // ここで $e->__toString() が暗黙的に呼び出される
35    echo PHP_EOL . "----------------------------------------" . PHP_EOL;
36}

UnexpectedValueException::__toString()メソッドは、例外オブジェクトが文字列として扱われる際に自動的に呼び出され、その例外に関する詳細情報を整形された文字列として返します。このメソッドに引数はなく、戻り値は例外の詳細情報を含む文字列です。

サンプルコードでは、数値の配列を処理するprocessNumbers関数を定義しています。この関数は、配列内に予期しない値、つまり数値ではない文字列'thirty'を見つけると、UnexpectedValueExceptionをスローします。

プログラムはtry...catchブロックで実行され、スローされた例外はcatchブロックで変数$eに捕捉されます。重要なのはecho $e;という記述です。ここで例外オブジェクト$eを直接出力しようとすると、PHPの内部で自動的に$e->__toString()メソッドが呼び出されます。その結果、__toString()メソッドが生成した文字列、すなわち例外メッセージ、エラーが発生したファイル名、行番号、そして処理の呼び出し履歴（スタックトレース）が画面に出力されます。

このように__toString()メソッドは、例外発生時にその詳細情報を簡単に文字列として取得し、ログ出力やデバッグに役立てるための便利な機能です。