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

Copy
1<?php
2
3/**
4 * カスタム例外クラスを定義し、オブジェクトのクローン時に動作する
5 * `__clone` マジックメソッドの例を示します。
6 * Exception クラス自体にはユーザーが `__clone` をオーバーライドする機会はありませんが、
7 * その子クラスではクローン時の挙動をカスタマイズできます。
8 */
9class MyCustomException extends Exception
10{
11    private string $context;
12
13    /**
14     * コンストラクタ
15     *
16     * @param string $message 例外メッセージ
17     * @param int $code 例外コード
18     * @param Throwable|null $previous 前の例外
19     * @param string $context 例外が発生したコンテキスト情報
20     */
21    public function __construct(string $message, int $code = 0, ?Throwable $previous = null, string $context = 'default')
22    {
23        parent::__construct($message, $code, $previous);
24        $this->context = $context;
25    }
26
27    /**
28     * 例外のコンテキストを取得します。
29     *
30     * @return string
31     */
32    public function getContext(): string
33    {
34        return $this->context;
35    }
36
37    /**
38     * オブジェクトが `clone` キーワードによって複製されたときに自動的に呼び出されるマジックメソッドです。
39     * 引数はなく、戻り値は `void` です。
40     * このメソッドが呼び出される前に、新しいオブジェクトには元のオブジェクトのプロパティがすべてコピーされています。
41     * ここでは、クローンされたオブジェクトのカスタムプロパティを初期化または変更する例を示します。
42     *
43     * PHPの内部的な `Exception::__clone()` も同様に引数なしで `void` を返します。
44     */
45    public function __clone()
46    {
47        // 親クラス（Exception）のプロパティは自動的にシャローコピーされます。
48        // `$this->message` や `$this->code` などは元のオブジェクトと同じ値を持っています。
49
50        // ここでは、カスタムプロパティである `$context` をクローン用に変更します。
51        // これは、クローンされた例外が元の例外とは異なる用途やコンテキストで
52        // 扱われる場合に、その状態を調整するのに役立ちます。
53        $this->context = 'cloned_context';
54
55        // 必要であれば、他のプロパティも変更できます。
56        // 例: $this->message = "Cloned: " . $this->getMessage();
57    }
58}
59
60// ----------------------------------------------------------------------------------------------------
61// サンプルコードの実行部分
62// ----------------------------------------------------------------------------------------------------
63
64// 1. 元の例外オブジェクトを作成します。
65$originalException = new MyCustomException("オリジナルエラー発生", 500, null, '処理A');
66
67echo "--- 元の例外オブジェクト ---" . PHP_EOL;
68echo "メッセージ: " . $originalException->getMessage() . PHP_EOL;
69echo "コード: " . $originalException->getCode() . PHP_EOL;
70echo "コンテキスト: " . $originalException->getContext() . PHP_EOL;
71echo "オブジェクトID: " . spl_object_id($originalException) . PHP_EOL; // オブジェクトのユニークID
72echo PHP_EOL;
73
74// 2. `clone` キーワードを使って元の例外オブジェクトを複製（クローン）します。
75//    この操作により、`MyCustomException` クラスで定義した `__clone()` メソッドが
76//    自動的に呼び出されます。
77$clonedException = clone $originalException;
78
79echo "--- クローンされた例外オブジェクト ---" . PHP_EOL;
80echo "メッセージ: " . $clonedException->getMessage() . PHP_EOL;
81echo "コード: " . $clonedException->getCode() . PHP_EOL;
82echo "コンテキスト: " . $clonedException->getContext() . PHP_EOL; // `__clone` で変更された値
83echo "オブジェクトID: " . spl_object_id($clonedException) . PHP_EOL; // 元とは異なるID
84echo PHP_EOL;
85
86// 3. 元のオブジェクトとクローンされたオブジェクトが異なるインスタンスであることを確認します。
87echo "元の例外とクローンされた例外は同じオブジェクトですか？ " . ($originalException === $clonedException ? "はい" : "いいえ") . PHP_EOL;
88
89// 出力から、`clone` 操作によって新しいオブジェクトが生成され、
90// その際に `MyCustomException` の `__clone` メソッドが呼ばれて
91// `$context` プロパティが 'cloned_context' に変更されたことが分かります。
92// 標準の `Exception` クラスの `__clone` はPHP内部で同様に動作しますが、
93// その挙動はユーザーからは変更できません。

PHPのException::__cloneは、Exceptionオブジェクトが複製される際に内部で動作する特殊なメソッドです。Exceptionクラス自体で直接オーバーライドすることはできませんが、その子クラスでは、オブジェクト複製時の挙動をカスタマイズするために利用できます。cloneキーワードを用いてオブジェクトを複製すると、新しいオブジェクトが生成された直後に、この__cloneマジックメソッドが自動的に呼び出されます。このメソッドは引数を取らず、戻り値もありません（void）。__cloneが実行される前には、新しいオブジェクトに元のオブジェクトのすべてのプロパティがシャローコピーされています。そのため、__cloneメソッド内では、複製されたオブジェクトの特定のプロパティを再初期化したり、元のオブジェクトとは異なる状態に調整したりする処理を記述します。サンプルコードでは、MyCustomExceptionクラスが__cloneを実装し、カスタムプロパティである$contextの値を「cloned_context」に変更しています。これにより、オリジナルの例外とクローンされた例外は、メッセージやコードは同じでも、$contextの値が異なる、完全に独立した新しいオブジェクトとして扱われることを示しています。このように__cloneは、オブジェクトの複製時に特別な初期化や状態変更が必要な場合に活用できる重要な仕組みです。

Copy
1<?php
2
3/**
4 * サブオブジェクトクラス
5 * ディープコピーの例で参照されるオブジェクトとして使用します。
6 */
7class SubObject
8{
9    public int $id;
10    public string $name;
11
12    public function __construct(int $id, string $name)
13    {
14        $this->id = $id;
15        $this->name = $name;
16    }
17
18    public function __toString(): string
19    {
20        return "SubObject[ID: {$this->id}, Name: {$this->name}]";
21    }
22}
23
24/**
25 * メインオブジェクトクラス
26 * 参照型のプロパティ（SubObject）を持ち、__clone メソッドでディープコピーを実装する例です。
27 *
28 * PHPの組み込みクラスであるExceptionには、内部的に__cloneメソッドが存在しますが、
29 * 通常、ユーザーがExceptionオブジェクトをクローンしたり、その__cloneメソッドをオーバーライドしたりすることはありません。
30 * このサンプルコードは、__cloneマジックメソッドが、オブジェクトの「ディープコピー」を
31 * 実現するためにどのように使用されるかを示す汎用的な例です。
32 */
33class MyClass
34{
35    public int $value;
36    public SubObject $subObject;
37
38    public function __construct(int $value, SubObject $subObject)
39    {
40        $this->value = $value;
41        $this->subObject = $subObject;
42    }
43
44    /**
45     * オブジェクトがクローンされた直後に呼び出されるマジックメソッドです。
46     * PHPの標準的なクローンは「シャローコピー」（浅いコピー）であり、
47     * 参照型のプロパティは元のオブジェクトとクローンされたオブジェクトで同じインスタンスを共有します。
48     * このメソッド内で参照型のプロパティも個別にクローンすることで、
49     * 元のオブジェクトと完全に独立した「ディープコピー」を作成できます。
50     */
51    public function __clone()
52    {
53        // subObject プロパティがオブジェクトであるため、
54        // このプロパティも別途クローンして新しいインスタンスを割り当てます。
55        // これにより、元のオブジェクトとクローンされたオブジェクトが
56        // 異なる SubObject インスタンスを参照するようになり、ディープコピーが実現されます。
57        $this->subObject = clone $this->subObject;
58    }
59
60    public function __toString(): string
61    {
62        return "MyClass[Value: {$this->value}, SubObject: {$this->subObject}]";
63    }
64}
65
66// --- サンプル実行 ---
67
68// 元のオブジェクトを作成
69$originalSub = new SubObject(1, "Original Sub");
70$original = new MyClass(100, $originalSub);
71
72echo "--- 初期状態 ---\n";
73echo "元のオブジェクト: " . $original . "\n";
74// SubObjectのインスタンスが同じであることをハッシュ値で確認
75echo "元のSubObjectのハッシュ: " . spl_object_hash($original->subObject) . "\n\n";
76
77// オブジェクトをクローン（__clone メソッドが実行され、ディープコピーされる）
78$cloned = clone $original;
79
80echo "--- クローン後 ---\n";
81echo "クローンされたオブジェクト: " . $cloned . "\n";
82// __cloneによってSubObjectも新しくクローンされたため、異なるハッシュ値になることを確認
83echo "クローンされたSubObjectのハッシュ: " . spl_object_hash($cloned->subObject) . "\n\n";
84
85// 元のオブジェクトとクローンされたオブジェクトにそれぞれ変更を加えて、
86// ディープコピーされたことを確認します。
87$original->value = 200;
88$original->subObject->name = "Modified Original Sub";
89$original->subObject->id = 2;
90
91$cloned->value = 300;
92$cloned->subObject->name = "Modified Cloned Sub";
93$cloned->subObject->id = 3;
94
95echo "--- 変更後 ---\n";
96echo "変更後の元のオブジェクト: " . $original . "\n";
97echo "変更後のクローンされたオブジェクト: " . $cloned . "\n";
98
99// 出力から、元のオブジェクトとクローンされたオブジェクトの SubObject が
100// それぞれ独立して変更されていることが確認できます。
101// これは、__clone メソッドによって SubObject も個別にクローンされ、
102// 完全に独立したディープコピーが実現されたためです。

__cloneメソッドは、PHPでオブジェクトをcloneキーワードを使って複製した直後に自動的に呼び出される特殊な（マジック）メソッドです。

PHPにおける標準のオブジェクト複製は「シャローコピー」（浅いコピー）であり、オブジェクト内の参照型のプロパティ（別のオブジェクトなど）は、元のオブジェクトとクローンされたオブジェクトとで同じインスタンスを共有します。このため、片方のオブジェクトで参照型プロパティを変更すると、もう一方にも影響が及びます。

__cloneメソッドをクラス内で定義することで、この標準の挙動をカスタマイズし、より深いコピーを実現できます。特に、サンプルコードのようにメソッド内で参照型プロパティを改めてcloneすることで、元のオブジェクトと完全に独立した「ディープコピー」（深いコピー）を作成することが可能です。これにより、クローン後の各オブジェクトが持つ参照型プロパティもそれぞれ独立したインスタンスとなるため、片方の変更がもう一方に影響することはありません。

このメソッドは引数を受け取らず、値を返すこともありません（void）。サンプルコードでは、MyClassが持つSubObjectプロパティを__cloneメソッド内で個別にクローンしており、その結果、元のMyClassオブジェクトとクローンされたMyClassオブジェクトが独立したSubObjectを持つディープコピーが実現されていることを確認できます。

なお、ご提示のリファレンスにあるExceptionクラスの__cloneはPHPの内部で利用されるものであり、通常、開発者がExceptionオブジェクトを直接クローンしたり、その__cloneメソッドをオーバーライドしたりすることはありません。このサンプルコードは、一般的なPHPオブジェクトにおいて__cloneがディープコピーのためにどのように機能するかを説明する汎用的な例です。

Copy
1<?php
2
3/**
4 * オブジェクトが配列や他のオブジェクトをプロパティとして持つ場合の__cloneマジックメソッドの例。
5 * デフォルトのオブジェクト複製（シャローコピー）では、配列やオブジェクトは参照がコピーされます。
6 * __cloneメソッドを実装することで、これらのプロパティも個別に複製（ディープコピー）し、
7 * 複製元と複製先が互いに独立して変更できるようになります。
8 */
9class DataContainer
10{
11    public string $label;
12    public array $items;
13    public object $config;
14
15    /**
16     * コンストラクタでプロパティを初期化します。
17     */
18    public function __construct(string $label, array $items, object $config)
19    {
20        $this->label = $label;
21        $this->items = $items;
22        $this->config = $config;
23    }
24
25    /**
26     * オブジェクトが `clone` キーワードで複製される際に、自動的に呼び出されるマジックメソッドです。
27     * 引数はなく、戻り値は void です。
28     * ここで参照型のプロパティ（配列や他のオブジェクト）を個別に複製することで、
29     * 複製元と複製先のオブジェクトが独立した状態を持つようにします。
30     */
31    public function __clone(): void
32    {
33        // `items` プロパティ（配列）を新しい配列として複製します。
34        // これにより、元のオブジェクトとクローンされたオブジェクトの配列が独立します。
35        $this->items = [...$this->items]; // PHP 7.4+ で推奨される配列のコピー方法
36
37        // `config` プロパティ（オブジェクト）も `clone` して複製します。
38        // これにより、元のオブジェクトとクローンされたオブジェクトのconfigが独立します。
39        $this->config = clone $this->config;
40    }
41}
42
43// 設定オブジェクトの例 (stdClassを使用)
44$initialConfig = new stdClass();
45$initialConfig->version = '1.0';
46$initialConfig->active = true;
47
48// 元のオブジェクトを作成
49$originalContainer = new DataContainer(
50    'Original Data',
51    ['itemA', 'itemB'],
52    $initialConfig
53);
54
55echo "--- Original Object Initial State ---\n";
56echo "Label: " . $originalContainer->label . "\n";
57echo "Items: " . implode(', ', $originalContainer->items) . "\n";
58echo "Config Version: " . $originalContainer->config->version . "\n";
59echo "Config Active: " . ($originalContainer->config->active ? 'Yes' : 'No') . "\n\n";
60
61// originalContainer をクローンして新しいオブジェクトを作成
62$clonedContainer = clone $originalContainer;
63
64// クローンされたオブジェクトのプロパティを変更
65$clonedContainer->label = 'Cloned Data';
66$clonedContainer->items[] = 'itemC'; // クローンされた配列に要素を追加
67$clonedContainer->config->version = '2.0'; // クローンされたconfigオブジェクトのプロパティを変更
68$clonedContainer->config->active = false;
69
70echo "--- Cloned Object After Modification ---\n";
71echo "Label: " . $clonedContainer->label . "\n";
72echo "Items: " . implode(', ', $clonedContainer->items) . "\n";
73echo "Config Version: " . $clonedContainer->config->version . "\n";
74echo "Config Active: " . ($clonedContainer->config->active ? 'Yes' : 'No') . "\n\n";
75
76// 元のオブジェクトの状態を再確認
77echo "--- Original Object State (Should Be Unchanged) ---\n";
78echo "Label: " . $originalContainer->label . "\n";
79echo "Items: " . implode(', ', $originalContainer->items) . "\n";
80echo "Config Version: " . $originalContainer->config->version . "\n";
81echo "Config Active: " . ($originalContainer->config->active ? 'Yes' : 'No') . "\n\n";
82
83// 結果の解説:
84// `label` (string) はプリミティブ型なので、デフォルトのコピーで独立します。
85// `items` (array) と `config` (object) は参照型ですが、
86// `__clone` メソッド内で明示的に複製したため、元のオブジェクトとは独立した状態が保たれています。
87// もし `__clone` メソッドがなければ、`items` と `config` への変更は `originalContainer` にも影響していました。
88?>

__cloneマジックメソッドは、PHPでオブジェクトをcloneキーワードで複製する際に自動的に呼び出される特別なメソッドです。引数はなく、戻り値もありません（void）。

PHPのデフォルトのオブジェクト複製（シャローコピー）では、文字列などの単純な値は個別にコピーされますが、配列や他のオブジェクト（参照型）は参照が共有されます。そのため、クローンされたオブジェクトで参照型プロパティを変更すると、元のオブジェクトにも影響が及んでしまいます。

この問題を解決し、完全に独立したオブジェクトを生成するために__cloneメソッドを使用します。メソッド内で、参照型のプロパティを明示的に個別に複製する処理を記述します。

サンプルコードのDataContainerクラスでは、items（配列）プロパティをスプレッド演算子...で新しい配列として、config（オブジェクト）プロパティはcloneキーワードで複製しています。

これにより、originalContainerをcloneして作られたclonedContainerが、配列やオブジェクトプロパティにおいても元のオブジェクトとは完全に独立し、互いの変更に影響されない安全なオブジェクト複製を実現します。

Copy
1<?php
2
3/**
4 * DateTimeオブジェクトのクローン例
5 *
6 * DateTimeオブジェクトはミュータブル（変更可能）なため、
7 * 元のオブジェクトの状態を保ちつつ、新しいオブジェクトで日時操作を行う際にクローンがよく使われます。
8 */
9$originalDateTime = new DateTime('2023-01-01 10:00:00');
10$clonedDateTime = clone $originalDateTime;
11
12// クローンされたオブジェクトを変更しても、元のオブジェクトには影響しません。
13$clonedDateTime->modify('+1 hour');
14
15echo "Original DateTime: " . $originalDateTime->format('Y-m-d H:i:s') . PHP_EOL;
16echo "Cloned DateTime:   " . $clonedDateTime->format('Y-m-d H:i:s') . PHP_EOL;
17
18echo PHP_EOL;
19
20/**
21 * Exceptionオブジェクトのクローン例
22 *
23 * Exceptionクラスにも内部的に__cloneメソッドが存在し、オブジェクトをクローンできます。
24 * ただし、Exceptionクラスの__cloneメソッドはfinalであるため、サブクラスでオーバーライドできません。
25 * 通常、Exceptionオブジェクトをクローンする実用的なユースケースは稀です。
26 */
27$originalException = new Exception('何らかのエラーが発生しました', 500);
28$clonedException = clone $originalException;
29
30// クローンされた例外オブジェクトのプロパティは、元のオブジェクトと同じ内容になります。
31echo "Original Exception Message: " . $originalException->getMessage() . PHP_EOL;
32echo "Cloned Exception Message:   " . $clonedException->getMessage() . PHP_EOL;
33echo "Original Exception Code: " . $originalException->getCode() . PHP_EOL;
34echo "Cloned Exception Code:   " . $clonedException->getCode() . PHP_EOL;
35
36// クローンされたオブジェクトは、元のオブジェクトとは異なる独立したインスタンスです。
37echo "Are they the same object? " . ($originalException === $clonedException ? 'Yes' : 'No') . PHP_EOL;
38

PHP 8のExceptionクラスには、オブジェクトを複製するための内部メソッド__cloneが存在します。このメソッドはオブジェクトをcloneキーワードで複製する際に自動的に呼び出され、引数を取らず、戻り値もありません。__cloneメソッドは、既存のオブジェクトと全く同じプロパティ値を持つ新しい独立したオブジェクトを作成するために使用されます。

サンプルコードのDateTimeオブジェクトの例は、cloneの有用性をよく示しています。DateTimeのようなミュータブル（変更可能）なオブジェクトの場合、cloneすることで元のオブジェクトの状態を保ちながら、複製した新しいオブジェクトで日時操作を行うことができます。これにより、意図せず元のオブジェクトが変更されてしまうことを防げます。

Exceptionクラスのオブジェクトもcloneキーワードを使って複製できます。複製されたExceptionオブジェクトは、元のオブジェクトと同じエラーメッセージやエラーコードなどのプロパティを持ちますが、メモリ上では元のオブジェクトとは異なる、完全に独立したインスタンスとなります。Exceptionクラスの__cloneメソッドはfinalとして定義されているため、サブクラスでこの複製処理の挙動をオーバーライドすることはできません。通常、Exceptionオブジェクトを直接クローンする実用的なケースは稀ですが、PHPのオブジェクトの複製メカニズムの一部として機能しています。