【PHP8.x】Dom\DocumentType::__wakeup()メソッドの使い方

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * __wakeup マジックメソッドの基本的な動作を説明するためのクラス。
7 *
8 * __wakeupは、unserialize()がオブジェクトを再構築した直後に呼び出されます。
9 * リソースの再接続など、デシリアライズ時に必要な初期化処理を実装するために使用されます。
10 */
11class ResourceHandler
12{
13    private string $name;
14    private string $status;
15
16    public function __construct(string $name)
17    {
18        $this->name = $name;
19        $this->status = 'Constructed';
20        echo "オブジェクト '{$this->name}' が生成されました。(状態: {$this->status})" . PHP_EOL;
21    }
22
23    /**
24     * unserialize() 時に自動的に呼び出されるマジックメソッド。
25     *
26     * このメソッドは、オブジェクトの状態を復元・検証する重要な役割を担います。
27     *
28     * [キーワード解説: __wakeup bypass]
29     * PHP 7.4より前のバージョンには、特殊なシリアライズ文字列を用いることで
30     * この __wakeup() の呼び出しを回避（バイパス）できる脆弱性が存在しました。
31     * これにより、このメソッド内で行うべき重要な初期化処理が実行されず、
32     * 意図しない状態のオブジェクトが生成される危険性がありました。
33     * 現在のPHPバージョンでは、この脆弱性は修正されています。
34     *
35     * ちなみに、リファレンスにある Dom\DocumentType::__wakeup は、
36     * 意図的に例外をスローすることで、このクラスのオブジェクトがデシリアライズされることを
37     * 根本的に禁止し、セキュリティを確保しています。
38     */
39    public function __wakeup(): void
40    {
41        $this->status = 'Woken up';
42        echo "オブジェクト '{$this->name}' が __wakeup により復元されました。(状態: {$this->status})" . PHP_EOL;
43    }
44
45    public function getStatus(): string
46    {
47        return $this->status;
48    }
49}
50
51// 1. オブジェクトをインスタンス化します。
52$obj = new ResourceHandler('SampleResource');
53
54// 2. オブジェクトをシリアライズ（文字列に変換）します。
55$serialized = serialize($obj);
56echo "シリアライズされたデータ: " . $serialized . PHP_EOL;
57
58// 3. シリアライズされたデータからオブジェクトをデシリアライズします。
59// この処理の過程で __wakeup() が自動的に呼び出されます。
60echo "デシリアライズを実行します..." . PHP_EOL;
61$unserializedObj = unserialize($serialized);
62
63// 4. 復元されたオブジェクトの状態を確認します。
64echo "復元されたオブジェクトの状態: " . $unserializedObj->getStatus() . PHP_EOL;
65

__wakeup()は、unserialize()関数によって文字列データからオブジェクトが復元される際に、自動的に呼び出されるマジックメソッドです。オブジェクトが復元された直後に、データベース接続の再確立やリソースの初期化といった、追加の処理を実行するために使用されます。

このサンプルコードでは、まずResourceHandlerクラスのオブジェクトを生成し、serialize()関数で文字列に変換しています。次に、unserialize()関数を使ってこの文字列からオブジェクトを復元します。この復元の過程で__wakeup()メソッドが自動的に実行され、オブジェクトのstatusプロパティが'Constructed'から'Woken up'へと更新されます。これにより、メソッドが正しく呼び出されたことを確認できます。このメソッドに引数はなく、戻り値もありません（void）。

ちなみに、古いPHPバージョンには__wakeup()の実行を回避できる「__wakeup bypass」という脆弱性が存在しましたが、現在は修正されています。リファレンスにあるDom\DocumentTypeクラスの__wakeupメソッドは、意図的にデシリアライズを禁止することで、この種の脆弱性から保護する設計になっています。

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * __wakeupマジックメソッドの動作を示すサンプルクラス
7 *
8 * このクラスは、オブジェクトがデシリアライズ（unserialize）される際に、
9 * 自動的にリソースの再接続などを行う一般的な使用例を示します。
10 */
11class Connection
12{
13    private string $dataSourceName;
14
15    // データベース接続のような、シリアライズできないリソースを想定
16    private ?stdClass $resource = null;
17
18    public function __construct(string $dsn)
19    {
20        $this->dataSourceName = $dsn;
21        $this->connect();
22    }
23
24    /**
25     * オブジェクトのシリアライズ時に呼び出されます。
26     * シリアライズするプロパティの配列を返します。
27     * ここでは、シリアライズできないリソース($resource)を除外します。
28     *
29     * @return string[]
30     */
31    public function __sleep(): array
32    {
33        echo "1. __sleep() が呼び出されました。接続をクリーンアップします。\n";
34        // シリアライズ前にリソースを解放
35        $this->resource = null;
36        return ['dataSourceName'];
37    }
38
39    /**
40     * オブジェクトのデシリアライズ（unserialize）完了後に呼び出されます。
41     *
42     * データベース接続の再確立など、オブジェクトが利用可能になるための
43     * 初期化処理をここで行います。
44     */
45    public function __wakeup(): void
46    {
47        echo "3. __wakeup() が呼び出されました。接続を再確立します。\n";
48        $this->connect();
49    }
50
51    /**
52     * 接続を確立する（シミュレーション）
53     */
54    private function connect(): void
55    {
56        // 実際にはここでデータベース接続などを行います
57        $this->resource = new stdClass();
58        echo "-> 接続が確立されました。\n";
59    }
60
61    /**
62     * 接続状態を確認します。
63     */
64    public function isConnected(): bool
65    {
66        return $this->resource !== null;
67    }
68}
69
70// ---- 実行コード ----
71
72// オブジェクトをインスタンス化します。コンストラクタで接続が確立されます。
73$connection = new Connection('mysql:host=localhost;dbname=test');
74echo 'オブジェクト生成後の接続状態: ' . ($connection->isConnected() ? 'true' : 'false') . "\n\n";
75
76// オブジェクトをシリアライズします。このとき __sleep() が呼ばれます。
77$serializedObject = serialize($connection);
78echo "2. オブジェクトがシリアライズされました: {$serializedObject}\n";
79echo 'シリアライズ後の元のオブジェクトの接続状態: ' . ($connection->isConnected() ? 'true' : 'false') . "\n\n";
80
81// シリアライズされた文字列からオブジェクトを復元します。このとき __wakeup() が呼ばれます。
82$restoredConnection = unserialize($serializedObject);
83echo "4. オブジェクトがデシリアライズされました。\n";
84echo '復元後のオブジェクトの接続状態: ' . ($restoredConnection->isConnected() ? 'true' : 'false') . "\n";

__wakeupは、unserialize()関数によってオブジェクトが文字列から復元された直後に、自動的に呼び出されるマジックメソッドです。このメソッドの主な目的は、シリアライズ（オブジェクトの文字列化）の過程で維持できないリソースを再初期化することです。

サンプルコードのConnectionクラスは、データベース接続の動作を模倣しています。オブジェクトをserialize()関数で文字列に変換する際には、対になる__sleep()メソッドが呼ばれ、接続リソースが一度クリーンアップされます。これにより、接続情報を含まない安全な状態でオブジェクトを保存できます。

その後、unserialize()関数を使ってこの文字列からオブジェクトを復元すると、__wakeup()メソッドが自動的に実行されます。このメソッド内で再度connect()メソッドを呼び出すことで、データベース接続が再確立され、オブジェクトは再び利用可能な状態に戻ります。

このように__wakeup()は、オブジェクトが復元された際に必要な初期化処理を自動で行うために使用されます。このメソッドは引数を取らず、戻り値もありません（void）。