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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 固定サイズのデータ構造を表すクラス。
7 *
8 * このクラスは、内部的に配列を使用し、指定された最大容量を超えて
9 * 要素を追加しようとすると OverflowException をスローします。
10 */
11class LimitedArrayContainer
12{
13    /**
14     * @param int $maxSize コンテナが保持できる要素の最大数
15     * @param array<int, mixed> $items 内部的に要素を保持する配列
16     */
17    public function __construct(
18        private int $maxSize,
19        private array $items = []
20    ) {
21    }
22
23    /**
24     * コンテナに要素を追加します。
25     *
26     * @param mixed $item 追加する要素
27     * @throws OverflowException コンテナが満杯の場合
28     */
29    public function addItem(mixed $item): void
30    {
31        // 配列の現在の要素数が最大サイズ以上かチェック
32        if (count($this->items) >= $this->maxSize) {
33            // 容量オーバーなので、OverflowExceptionをスローする
34            throw new OverflowException('Container is full. Cannot add more items.');
35        }
36        $this->items[] = $item;
37        echo "Added item: " . (is_scalar($item) ? $item : gettype($item)) . PHP_EOL;
38    }
39}
40
41// メインの処理
42try {
43    // 最大3つの要素を保持できるコンテナを作成
44    $container = new LimitedArrayContainer(3);
45
46    // 意図的に容量を超える数の要素を追加して例外を発生させる
47    $container->addItem('Apple');
48    $container->addItem('Banana');
49    $container->addItem('Cherry');
50    $container->addItem('Durian'); // この行で例外がスローされる
51
52} catch (OverflowException $e) {
53    // catchブロックでOverflowExceptionオブジェクトを捕捉する
54    echo "--------------------" . PHP_EOL;
55    echo "An exception occurred:" . PHP_EOL;
56
57    // 例外オブジェクトをechoで出力すると、自動的に__toString()メソッドが呼び出される。
58    // __toString()は、例外のクラス名、メッセージ、発生場所、スタックトレースなどを含む
59    // 整形された文字列を返す。
60    echo $e;
61}

このPHPサンプルコードは、配列の容量が上限に達した際に発生する OverflowException という例外の情報を、__toStringメソッドを使って文字列として表示する例です。

コード内では、まず最大3つの要素しか保持できない LimitedArrayContainer クラスを定義しています。このクラスの addItem メソッドを使い、意図的に4つ目の要素を追加しようとすると、配列の容量が上限を超えるため OverflowException が発生します。

try-catch構文によってこの例外が捕捉されると、catchブロック内の処理が実行されます。ここで、捕捉した例外オブジェクト（変数 $e）を echo で出力しようとすると、PHPは自動的にそのオブジェクトの __toString メソッドを呼び出します。

OverflowException の __toString メソッドは引数を持たず、戻り値として例外に関する詳細情報を含んだ文字列（string）を返します。この文字列には、例外のクラス名、エラーメッセージ、例外が発生したファイル名と行番号、そしてそこに至るまでの処理の呼び出し履歴（スタックトレース）が整形されて含まれています。これにより、エラーの原因を特定しやすくなります。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 固定容量のスタックを表すクラス。
7 * 容量を超えて要素を追加しようとすると OverflowException をスローします。
8 */
9final class FixedSizeStack
10{
11    private array $items = [];
12
13    public function __construct(
14        private readonly int $capacity
15    ) {
16        if ($this->capacity < 1) {
17            throw new InvalidArgumentException('Capacity must be greater than 0.');
18        }
19    }
20
21    /**
22     * スタックに要素を追加します。
23     *
24     * @param mixed $item 追加する要素
25     * @throws OverflowException 容量が一杯の場合
26     */
27    public function push(mixed $item): void
28    {
29        if (count($this->items) >= $this->capacity) {
30            // 容量を超えたため、例外をスローする
31            throw new OverflowException("Stack is full. Cannot add more items.");
32        }
33        $this->items[] = $item;
34        echo "Pushed: " . $item . PHP_EOL;
35    }
36}
37
38try {
39    // 容量が3のスタックを作成
40    $stack = new FixedSizeStack(3);
41
42    $stack->push('A');
43    $stack->push('B');
44    $stack->push('C');
45
46    // この操作で容量を超えるため、OverflowExceptionが発生する
47    $stack->push('D');
48
49} catch (OverflowException $e) {
50    // catchブロックで例外オブジェクトを捕捉します。
51    // 例外オブジェクトをechoすると、内部的に__toString()メソッドが呼び出され、
52    // 例外に関する情報が整形された文字列として出力されます。
53    // これが他の言語における `toString()` の一般的な使われ方に相当します。
54    echo PHP_EOL . "Caught exception:" . PHP_EOL;
55    echo $e;
56}

OverflowException::__toString()メソッドは、OverflowExceptionオブジェクトが持つ例外情報を、人間が読みやすい文字列形式で取得するために使用されます。これはPHPの「マジックメソッド」の一つであり、オブジェクトを文字列として扱おうとした際に自動的に呼び出される特別なメソッドです。

このメソッドに引数はありません。戻り値として、例外メッセージ、例外が発生したファイル名、行番号、そして処理の呼び出し履歴であるスタックトレースなど、デバッグに役立つ情報が整形されたstring（文字列）を返します。

サンプルコードでは、容量が固定されたスタックに許容量を超える要素を追加しようとして、意図的にOverflowExceptionを発生させています。try-catch構文のcatchブロックで、発生した例外は$eという変数（オブジェクト）に格納されます。echo $e;と記述すると、PHPは内部で自動的に$eオブジェクトの__toString()メソッドを呼び出します。その結果、例外に関する詳細な情報が文字列として画面に出力され、エラー内容を簡単に確認できます。これは、他のプログラミング言語におけるtoString()メソッドの機能に相当します。