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

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * 容量オーバーを表すカスタム例外クラス。
7 * OverflowExceptionを継承し、PHP 8のコンストラクタプロパティ昇格を利用しています。
8 *
9 * @see https://www.php.net/manual/ja/language.oop5.decon.php#language.oop5.decon.constructor.promotion
10 */
11class CapacityException extends \OverflowException
12{
13    /**
14     * コンストラクタ。
15     *
16     * コンストラクタの引数に可視性修飾子(public)を付与することで、
17     * プロパティの宣言と、コンストラクタ内での値の代入を同時に行います。
18     * これが「コンストラクタのプロパティ昇格」です。
19     *
20     * @param int $maxCapacity 許容される最大容量
21     * @param int $attemptedValue 試行された値
22     * @param string $message 例外メッセージ
23     * @param int $code 例外コード
24     * @param ?\Throwable $previous 前の例外
25     */
26    public function __construct(
27        public readonly int $maxCapacity,
28        public readonly int $attemptedValue,
29        string $message = "Capacity exceeded.",
30        int $code = 0,
31        ?\Throwable $previous = null
32    ) {
33        // 親クラスであるOverflowExceptionのコンストラクタを呼び出す
34        parent::__construct($message, $code, $previous);
35    }
36}
37
38/**
39 * 値を配列に追加するデモ関数。
40 *
41 * @param array<int> $items
42 * @param int $value
43 * @param int $maxCapacity
44 * @return array<int>
45 * @throws CapacityException
46 */
47function addValue(array $items, int $value, int $maxCapacity): array
48{
49    if (count($items) >= $maxCapacity) {
50        // 容量を超えた場合、カスタム例外をスローする
51        throw new CapacityException($maxCapacity, $value);
52    }
53    $items[] = $value;
54    return $items;
55}
56
57// メイン処理
58$list = [10, 20, 30];
59$limit = 3;
60
61try {
62    echo "現在のリスト: " . implode(', ', $list) . "\n";
63    echo "最大容量: {$limit}\n";
64    echo "値を追加します...\n";
65    // わざと容量オーバーを発生させる
66    $list = addValue($list, 40, $limit);
67    echo "新しいリスト: " . implode(', ', $list) . "\n";
68} catch (CapacityException $e) {
69    // スローされた例外をキャッチし、プロパティにアクセスする
70    echo "----------------------------------------\n";
71    echo "エラー: " . $e->getMessage() . "\n";
72    echo "許容される最大容量: " . $e->maxCapacity . "\n";
73    echo "追加しようとした値: " . $e->attemptedValue . "\n";
74    echo "ファイル: " . $e->getFile() . " on line " . $e->getLine() . "\n";
75    echo "----------------------------------------\n";
76}

このPHPサンプルコードは、OverflowExceptionを継承して、特定の状況（この場合は配列の容量オーバー）に対応する独自の例外クラスCapacityExceptionを作成する例です。

OverflowExceptionのコンストラクタ__constructは、例外オブジェクトが生成される際に自動的に呼び出されます。引数として、エラーメッセージを表す文字列$message、エラーコードの整数$code、そして連鎖する前の例外$previousを受け取ります。このメソッドは値を返しません。

サンプルコードのCapacityExceptionクラスでは、PHP 8の新機能である「コンストラクタのプロパティ昇格」が使われています。コンストラクタの引数にpublic readonlyのような可視性修飾子を付けることで、プロパティの宣言とコンストラクタ内での値の代入を同時に行い、コードを簡潔にしています。コンストラクタ内ではparent::__construct()を呼び出し、親クラスであるOverflowExceptionのコンストラクタに必要な情報を渡しています。

メイン処理では、addValue関数で意図的に容量オーバーを発生させ、スローされたCapacityExceptionをtry-catchブロックで捕捉します。catchブロック内では、getMessage()のような親クラスから継承したメソッドに加え、$e->maxCapacityのようにCapacityExceptionで独自に定義したプロパティにもアクセスでき、より詳細なエラー情報を取得して処理を行っています。

Copy
1<?php
2
3/**
4 * OverflowException を継承したカスタム例外クラス。
5 * コンストラクタのプロパティ昇格機能を利用して、
6 * キューの最大容量(capacity)を追加情報として保持します。
7 */
8class QueueOverflowException extends OverflowException
9{
10    /**
11     * コンストラクタ。
12     *
13     * PHP 8.0 の "コンストラクタのプロパティ昇格" を使用しています。
14     * 引数に `public readonly int $capacity` と記述するだけで、
15     * public な読み取り専用の $capacity プロパティが宣言され、
16     * コンストラクタの引数から自動的に値が代入されます。
17     *
18     * @param int $capacity キューの最大容量
19     * @param string $message 例外メッセージ
20     * @param int $code 例外コード
21     * @param ?Throwable $previous 前の例外
22     */
23    public function __construct(
24        public readonly int $capacity,
25        string $message = "",
26        int $code = 0,
27        ?Throwable $previous = null
28    ) {
29        // メッセージが指定されていない場合、容量情報を含むデフォルトメッセージを設定
30        if ($message === "") {
31            $message = "Queue has reached its capacity of {$this->capacity}.";
32        }
33
34        // 親クラスである OverflowException のコンストラクタを呼び出す
35        parent::__construct($message, $code, $previous);
36    }
37}
38
39/**
40 * 固定サイズのキューを表すクラス。
41 */
42class FixedSizeQueue
43{
44    private array $items = [];
45
46    // ここでもコンストラクタのプロパティ昇格を利用
47    public function __construct(private readonly int $capacity)
48    {
49    }
50
51    /**
52     * キューにアイテムを追加します。
53     *
54     * @param mixed $item 追加するアイテム
55     * @throws QueueOverflowException キューが満杯の場合
56     */
57    public function enqueue(mixed $item): void
58    {
59        if (count($this->items) >= $this->capacity) {
60            // キューが満杯の場合、カスタム例外をスローする
61            throw new QueueOverflowException($this->capacity);
62        }
63
64        $this->items[] = $item;
65        echo "Enqueued: {$item}" . PHP_EOL;
66    }
67}
68
69// --- 実行コード ---
70try {
71    // 容量が2のキューを作成
72    $queue = new FixedSizeQueue(2);
73
74    $queue->enqueue('A');
75    $queue->enqueue('B');
76
77    // 3つ目のアイテムを追加しようとすると、容量オーバーで例外が発生する
78    $queue->enqueue('C');
79
80} catch (QueueOverflowException $e) {
81    // 発生したカスタム例外を捕捉する
82    echo "--------------------" . PHP_EOL;
83    echo "Exception Caught!" . PHP_EOL;
84    echo "Message: " . $e->getMessage() . PHP_EOL;
85    // プロパティ昇格で定義されたプロパティに直接アクセスできる
86    echo "Queue Capacity: " . $e->capacity . PHP_EOL;
87    echo "File: " . $e->getFile() . PHP_EOL;
88    echo "Line: " . $e->getLine() . PHP_EOL;
89}

このサンプルコードは、PHPの組み込み例外クラスであるOverflowExceptionを継承して、独自のカスタム例外クラスQueueOverflowExceptionを作成する例です。PHP 8.0から導入された「コンストラクタのプロパティ昇格」という便利な機能の活用方法を示しています。

OverflowExceptionのコンストラクタ__constructは、例外オブジェクトが生成される際に呼び出され、引数として受け取った例外メッセージ $message や例外コード $code などをオブジェクトのプロパティに設定します。このメソッド自体に戻り値はありません。

サンプルコードのQueueOverflowExceptionクラスは、このコンストラクタを拡張しています。引数リストでpublic readonly int $capacityと記述するだけで、capacityという公開プロパティの宣言と、コンストラクタ内での値の代入が同時に行われます。これが「コンストラクタのプロパティ昇格」で、コードを簡潔に記述できます。これにより、キューが満杯になった際の最大容量という追加情報を、例外オブジェクトに簡単に持たせることが可能になります。処理の最後ではparent::__construct()を呼び出し、親クラスのコンストラクタに必要な情報を渡しています。

実行コードでは、容量を超えたキューに要素を追加して意図的に例外を発生させ、catchブロックで捕捉しています。$e->getMessage()でメッセージを取得できるだけでなく、プロパティ昇格で定義された$e->capacityにも直接アクセスし、例外発生時の詳細情報を取得していることがわかります。