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

Copy
1<?php
2
3/**
4 * カスタム例外クラス。
5 * Exception を継承し、オブジェクトが unserialize() された際に呼び出される
6 * __wakeup マジックメソッドの動作を示すための例です。
7 */
8class MyCustomException extends Exception
9{
10    private string $context;
11
12    /**
13     * コンストラクタ
14     *
15     * @param string $message 例外メッセージ
16     * @param int $code 例外コード
17     * @param Throwable|null $previous 前の例外
18     * @param string $context 例外に関連する追加情報
19     */
20    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null, string $context = "default")
21    {
22        parent::__construct($message, $code, $previous);
23        $this->context = $context;
24        echo "[DEBUG] MyCustomException::__construct called. Message: {$message}, Context: {$this->context}\n";
25    }
26
27    /**
28     * オブジェクトが unserialize() 関数によって復元された直後に呼び出されるマジックメソッドです。
29     * シリアライズ時に失われたリソースの再接続や、オブジェクトの状態の再初期化などに使用できます。
30     *
31     * Exception クラス自体には __wakeup メソッドは明示的に定義されていませんが、
32     * このように継承したカスタムクラスで独自に実装することで、復元時のカスタム処理を行えます。
33     * 引数なし、戻り値なし (void) で定義する必要があります。
34     */
35    public function __wakeup(): void
36    {
37        echo "[DEBUG] MyCustomException::__wakeup called. Object restored. Context: {$this->context}\n";
38        // ここで、例えばデータベース接続の再確立、ファイルの再オープン、特定プロパティの再計算など、
39        // オブジェクトが使える状態にするための復元処理を行うことができます。
40        $this->context .= " (restored at wakeup)"; // 復元されたことを示すためにコンテキストを変更
41    }
42
43    /**
44     * 例外のコンテキスト情報を取得します。
45     *
46     * @return string
47     */
48    public function getContext(): string
49    {
50        return $this->context;
51    }
52}
53
54// --- __wakeup メソッドの動作確認 ---
55
56echo "--- Step 1: 例外オブジェクトを作成します ---\n";
57// MyCustomException のインスタンスを作成すると、コンストラクタが呼ばれます。
58$originalException = new MyCustomException("データの整合性エラーが発生しました。", 500, null, "DB_TRANSACTION_FAILED");
59echo "元の例外オブジェクトのコンテキスト: " . $originalException->getContext() . "\n\n";
60
61echo "--- Step 2: オブジェクトをシリアライズします (文字列に変換) ---\n";
62// オブジェクトを serialize() 関数でシリアライズすると、その現在の状態が文字列として保存されます。
63// この時点では __wakeup() は呼び出されません。
64$serializedException = serialize($originalException);
65echo "シリアライズされた文字列:\n" . $serializedException . "\n\n";
66
67echo "--- Step 3: オブジェクトをデシリアライズします (文字列からオブジェクトに復元) ---\n";
68// unserialize() 関数が呼び出され、文字列から新しいオブジェクトが作成されます。
69// この処理の直後に、MyCustomException クラスの __wakeup() メソッドが自動的に実行されます。
70$restoredException = unserialize($serializedException);
71echo "\n"; // __wakeup の出力との区切りを良くするため
72
73echo "--- Step 4: 復元されたオブジェクトの情報を確認します ---\n";
74if ($restoredException instanceof MyCustomException) {
75    echo "復元された例外メッセージ: " . $restoredException->getMessage() . "\n";
76    echo "復元された例外コード: " . $restoredException->getCode() . "\n";
77    echo "復元された例外オブジェクトのコンテキスト: " . $restoredException->getContext() . "\n";
78    echo "-> __wakeup メソッドによりコンテキストが変更されたことが確認できます。\n";
79} else {
80    echo "例外オブジェクトの復元に失敗しました。\n";
81}

PHPにおける__wakeupマジックメソッドは、オブジェクトがunserialize()関数によって復元された直後に自動的に呼び出される特別なメソッドです。引数はなく、戻り値もありません（voidとして定義されます）。このメソッドの主な役割は、シリアライズ中に失われたリソースの再接続や、オブジェクトの内部状態の再初期化など、復元されたオブジェクトをすぐに利用可能な状態にするためのカスタム処理を行うことです。

Exceptionクラス自体には__wakeupメソッドは定義されていませんが、提供されたサンプルコードではExceptionを継承したカスタム例外クラスでこれを実装し、例外オブジェクトの復元時に独自の処理を組み込めることを示しています。

サンプルコードでは、MyCustomExceptionクラスに__wakeupメソッドが実装されています。MyCustomExceptionのインスタンスをserialize()関数で文字列化し、unserialize()関数で復元する過程で、この__wakeupメソッドが自動的に呼び出されます。メソッド内では、オブジェクトのcontextプロパティの値が変更されるように記述されており、復元されたオブジェクトのcontextプロパティを確認することで、__wakeupメソッドが実行され、カスタムロジックが適用されたことを視覚的に確認できます。これは、デシリアライズ時にオブジェクトの特定の初期化や調整が必要な場合に特に有用です。

Copy
1<?php
2
3/**
4 * MyCustomException class demonstrates the __wakeup magic method and its bypass for Exceptions.
5 * When an object derived from Exception is unserialized, PHP's internal mechanism
6 * specifically skips calling __wakeup if the 'trace' property is missing or null.
7 * This is a security feature to prevent potential exploits through a manipulated stack trace.
8 */
9class MyCustomException extends Exception
10{
11    private string $customData;
12
13    /**
14     * Constructor for MyCustomException.
15     *
16     * @param string $message The Exception message.
17     * @param int $code The Exception code.
18     * @param Throwable|null $previous The previous throwable for chaining.
19     * @param string $customData Custom data unique to this exception.
20     */
21    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null, string $customData = "Default Data")
22    {
23        parent::__construct($message, $code, $previous);
24        $this->customData = $customData;
25        echo "DEBUG: MyCustomException constructor called.\n";
26    }
27
28    /**
29     * The __wakeup magic method is called when an object is unserialized.
30     * For objects extending `Exception`, this method will be SKIPPED if
31     * the serialized string does not contain the 'trace' property or it's null.
32     */
33    public function __wakeup(): void
34    {
35        echo "DEBUG: MyCustomException __wakeup called. Custom data: " . $this->customData . "\n";
36        // In a real application, you might re-establish connections or validate state here.
37    }
38
39    /**
40     * Gets the custom data stored in the exception.
41     *
42     * @return string The custom data.
43     */
44    public function getCustomData(): string
45    {
46        return $this->customData;
47    }
48}
49
50// --- Demonstration of __wakeup behavior in Exceptions ---
51
52echo "--- Scenario 1: Normal serialization and unserialization ---\n";
53// Create an instance of our custom exception.
54$originalException = new MyCustomException(
55    "A standard exception for demonstration",
56    100,
57    null,
58    "Data from original object"
59);
60
61// Serialize the exception object.
62// PHP will include all standard Exception properties, including the 'trace'.
63$serializedNormal = serialize($originalException);
64echo "Serialized (normal): " . $serializedNormal . "\n\n";
65
66// Unserialize the object.
67// Because the 'trace' property is present in the serialized string, __wakeup should be called.
68echo "Attempting to unserialize normally...\n";
69$unserializedNormal = unserialize($serializedNormal);
70
71if ($unserializedNormal instanceof MyCustomException) {
72    echo "Result: Unserialized object is MyCustomException.\n";
73    echo "Result: Custom data: " . $unserializedNormal->getCustomData() . "\n";
74} else {
75    echo "Result: Unserialized object is NOT an instance of MyCustomException.\n";
76}
77echo "--- End Scenario 1 ---\n\n";
78
79
80echo "--- Scenario 2: Unserialization with 'trace' property removed (Wakeup Bypass) ---\n";
81echo "This demonstrates a '__wakeup bypass' specific to Exception objects.\n";
82echo "PHP's `unserialize()` function for `Exception` objects (and derived classes)\n";
83echo "*skips* calling the `__wakeup` magic method if the 'trace' property is\n";
84echo "missing or nullified in the serialized string. This is a security measure.\n\n";
85
86// A handcrafted serialized string for MyCustomException.
87// The 'O:LEN:"CLASS_NAME":PROPS_COUNT:{...}' format is used.
88// Important: The `s:5:"trace";...` entry, which would normally hold the stack trace,
89// has been deliberately *omitted*, and the `PROPS_COUNT` adjusted accordingly (from 7 to 6).
90// Also, private properties are serialized as `s:LENGTH:"\0CLASS_NAME\0PROPERTY_NAME";`.
91$handcraftedBypassString = 'O:17:"MyCustomException":6:{s:13:"*filePath";s:1:"a";s:13:"*fileLine";i:1;s:7:"message";s:23:"Handcrafted Bypass Error";s:4:"code";i:3;s:8:"previous";N;s:29:"'."\0".'MyCustomException'."\0".'customData";s:16:"Bypass Activated";}';
92echo "Serialized (handcrafted, 'trace' removed): " . $handcraftedBypassString . "\n\n";
93
94// Unserialize the handcrafted string.
95// Because the 'trace' property is missing, __wakeup should NOT be called.
96echo "Attempting to unserialize with handcrafted string...\n";
97$unserializedBypass = unserialize($handcraftedBypassString);
98
99if ($unserializedBypass instanceof MyCustomException) {
100    echo "Result: Unserialized object is MyCustomException.\n";
101    echo "Result: Custom data: " . $unserializedBypass->getCustomData() . "\n";
102    echo "Observation: If 'DEBUG: MyCustomException __wakeup called' was NOT displayed above,\n";
103    echo "             then the `__wakeup` bypass for Exception objects was successful.\n";
104} else {
105    echo "Result: Unserialized object is NOT an instance of MyCustomException.\n";
106}
107echo "--- End Scenario 2 ---\n";
108
109?>

PHP 8のExceptionクラスに含まれる__wakeupメソッドは、オブジェクトがデシリアライズ（unserialize関数で復元）される際に自動的に呼び出される特殊なマジックメソッドです。このメソッドは引数を受け取らず、値を返しません。通常、デシリアライズされたオブジェクトの内部状態を再初期化したり、データベース接続などを再確立したりする目的で利用されます。

しかし、Exceptionクラス、およびそれを継承するクラスの場合、この__wakeupメソッドには特別な挙動があります。PHPの内部機構は、シリアライズされたデータ内にスタックトレース情報であるtraceプロパティが存在しないか、またはnullである場合、セキュリティ上の理由から__wakeupメソッドの呼び出しを意図的にスキップします。これは、不正なシリアライズデータによる潜在的な脆弱性（unserialize関連の攻撃）を防ぐための重要な機能です。

サンプルコードでは、MyCustomExceptionというカスタム例外クラスを用いてこの挙動を具体的に示しています。最初のシナリオでは、通常の例外オブジェクトをシリアライズおよびデシリアライズすることで、__wakeupメソッドが問題なく呼び出されることを確認しています。続く二つ目のシナリオでは、意図的にtraceプロパティを削除したシリアライズ文字列を作成し、これをデシリアライズすることで、__wakeupメソッドが呼び出されない（バイパスされる）挙動を実演しています。出力されるデバッグメッセージの有無によって、__wakeupの呼び出しがスキップされたことを確認できます。

Copy
1<?php
2
3/**
4 * カスタム例外クラス。
5 * unserialize() 時に __wakeup() メソッドが呼び出されることを示すために使用します。
6 * PHPのExceptionクラス自体には__wakeupメソッドは定義されていませんが、
7 * 継承したクラスでマジックメソッドとして実装することができます。
8 */
9class MyCustomException extends Exception
10{
11    /**
12     * デシリアライズ時にオブジェクトの状態を再初期化するために呼び出されるマジックメソッド。
13     * unserialize() 関数によってオブジェクトが復元された直後に自動的に呼び出されます。
14     *
15     * @return void
16     */
17    public function __wakeup(): void
18    {
19        // ここにデシリアライズ後に実行したいロジックを記述します。
20        // 例: データベース接続の再確立、リソースの再取得、プロパティの検証など。
21        // 初心者向けに、ここではデシリアライズされたことを示すメッセージを出力します。
22        // error_log は、Webサーバーのエラーログまたはコマンドラインの標準エラー出力に記録されます。
23        error_log("MyCustomException::__wakeup() が呼び出されました。オブジェクトがデシリアライズされました。");
24    }
25
26    /**
27     * カスタム例外のコンストラクタ。
28     *
29     * @param string $message 例外メッセージ
30     * @param int $code 例外コード
31     * @param Throwable|null $previous 前の例外
32     */
33    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
34    {
35        parent::__construct($message, $code, $previous);
36        error_log("MyCustomException::__construct() が呼び出されました。");
37    }
38}
39
40/**
41 * MyCustomException のシリアライズとデシリアライズのデモンストレーションを行います。
42 * unserialize() 時に __wakeup() が呼び出されることを示します。
43 */
44function demonstrateExceptionWakeup(): void
45{
46    echo "--- オブジェクトの作成とシリアライズの開始 ---" . PHP_EOL;
47
48    // 1. カスタム例外オブジェクトを作成します。
49    // この時点でMyCustomException::__construct()が呼び出されます。
50    $originalException = new MyCustomException("これはカスタム例外メッセージです。", 100);
51    echo "オリジナル例外オブジェクト作成済み。" . PHP_EOL;
52
53    // 2. オブジェクトをシリアライズ (文字列に変換) します。
54    // オブジェクトの状態が文字列として保存されます。
55    $serializedException = serialize($originalException);
56    echo "例外オブジェクトをシリアライズしました: " . $serializedException . PHP_EOL . PHP_EOL;
57
58    echo "--- シリアライズされた文字列のデシリアライズの開始 ---" . PHP_EOL;
59
60    // 3. シリアライズされた文字列をデシリアライズ (オブジェクトに復元) します。
61    // この操作によって、MyCustomException::__wakeup() メソッドが自動的に呼び出されます。
62    $deserializedException = unserialize($serializedException);
63    echo "例外オブジェクトをデシリアライズしました。" . PHP_EOL;
64
65    // 4. デシリアライズされたオブジェクトが元のオブジェクトと同じタイプであることを確認します。
66    if ($deserializedException instanceof MyCustomException) {
67        echo "デシリアライズされたオブジェクトは MyCustomException のインスタンスです。" . PHP_EOL;
68        echo "メッセージ: " . $deserializedException->getMessage() . PHP_EOL;
69        echo "コード: " . $deserializedException->getCode() . PHP_EOL;
70    } else {
71        echo "エラー: オブジェクトのデシリアライズに失敗したか、予期しない型です。" . PHP_EOL;
72    }
73
74    echo PHP_EOL . "--- ログ出力の確認 ---" . PHP_EOL;
75    echo "MyCustomException::__wakeup() が呼び出されたことは、" . PHP_EOL;
76    echo "通常、実行環境のエラーログ（WebサーバーログやCLIの標準エラー出力）に記録されます。" . PHP_EOL;
77    echo "このサンプルコードを実行すると、そこに" . PHP_EOL;
78    echo "'MyCustomException::__wakeup() が呼び出されました。オブジェクトがデシリアライズされました。'" . PHP_EOL;
79    echo "というメッセージが出力されているはずです。" . PHP_EOL;
80}
81
82// デモンストレーション関数を実行します。
83demonstrateExceptionWakeup();
84

PHPの__wakeupメソッドは、オブジェクトがunserialize()関数によって復元（デシリアライズ）された直後に自動的に呼び出される特殊なマジックメソッドです。このメソッドは引数を取らず、戻り値もありません。主な役割は、デシリアライズされたオブジェクトが再び利用可能になった際に、その内部状態を適切に再初期化することです。例えば、データベース接続の再確立や、外部リソースの再取得など、シリアライズ中に失われた情報を復元する際に利用されます。

このサンプルコードでは、MyCustomExceptionというカスタム例外クラスを定義し、その中で__wakeupメソッドを実装しています。serialize()関数で作成した例外オブジェクトを文字列化し、その後unserialize()関数でその文字列から元のオブジェクトに復元する際に、MyCustomException::__wakeup()メソッドが自動的に実行されます。__wakeup内でerror_log()により出力されたメッセージは、通常、Webサーバーのエラーログやコマンドラインの標準エラー出力で確認でき、オブジェクトがデシリアライズされ、初期化処理が実行されたことを示します。

このように__wakeupを利用することで、保存したオブジェクトを読み込んだ際にも、必要な初期化処理を確実に実行できるため、アプリケーションの堅牢性を高める上で重要な機能です。

Copy
1<?php
2
3/**
4 * カスタムクラスの__wakeupメソッドの動作を示すクラス。
5 * 通常のクラスでは、unserialize()時に__wakeupが呼び出され、
6 * オブジェクトの初期化や状態の復元を行うことができます。
7 */
8class MyCustomClass
9{
10    public string $data;
11
12    public function __construct(string $data)
13    {
14        $this->data = $data;
15        echo "MyCustomClass::__construct()が呼び出されました: " . $this->data . PHP_EOL;
16    }
17
18    /**
19     * オブジェクトがデシリアライズされる直前に実行されます。
20     * ここでデシリアライズされたデータに対する追加処理を実行できます。
21     */
22    public function __wakeup(): void
23    {
24        echo "MyCustomClass::__wakeup()が呼び出されました。" . PHP_EOL;
25        $this->data = "Wakeupで修正されたデータ: " . $this->data;
26    }
27}
28
29/**
30 * Exceptionを継承したカスタムクラスの__wakeupメソッドの動作を示すクラス。
31 * PHP 7.0以降では、Exceptionクラスとその子孫クラスの__wakeupメソッドは、
32 * unserialize()時に自動的には呼び出されません。
33 * これは、デシリアライズ時のセキュリティ上のリスク（意図しないコード実行など）を
34 * 「回避」するためのPHPの内部的な変更によるものです。
35 */
36class MyExceptionChild extends Exception
37{
38    public string $additionalInfo;
39
40    public function __construct(string $message = "", string $additionalInfo = "", int $code = 0, ?Throwable $previous = null)
41    {
42        parent::__construct($message, $code, $previous);
43        $this->additionalInfo = $additionalInfo;
44        echo "MyExceptionChild::__construct()が呼び出されました: " . $this->message . PHP_EOL;
45    }
46
47    /**
48     * この__wakeupメソッドは定義されていますが、PHP 7.0以降の環境では
49     * unserialize()が呼び出されても自動的には実行されません。
50     * そのため、このメソッド内の処理は実行されず、関連するセキュリティ問題が「回避」されます。
51     */
52    public function __wakeup(): void
53    {
54        // このメッセージはPHP 7.0以降でunserialize()時に表示されることはありません。
55        echo "MyExceptionChild::__wakeup()が呼び出されました。(このメッセージは通常表示されません)" . PHP_EOL;
56        $this->additionalInfo = "Wakeupで変更されるはずだった追加情報"; // この行も実行されない
57    }
58}
59
60// --- 実行例 ---
61
62echo "--- MyCustomClassのデシリアライズ挙動 ---" . PHP_EOL;
63$customObject = new MyCustomClass("元のカスタムデータ");
64$serializedCustomObject = serialize($customObject);
65echo "シリアライズされたカスタムオブジェクト: " . $serializedCustomObject . PHP_EOL;
66$unserializedCustomObject = unserialize($serializedCustomObject);
67echo "デシリアライズ後のデータ: " . $unserializedCustomObject->data . PHP_EOL . PHP_EOL;
68
69echo "--- MyExceptionChildのデシリアライズ挙動 (PHP 7.0以降で__wakeupは呼び出されない) ---" . PHP_EOL;
70$exceptionObject = new MyExceptionChild("発生したエラー", "変更される前の追加情報");
71$serializedExceptionObject = serialize($exceptionObject);
72echo "シリアライズされた例外オブジェクト: " . $serializedExceptionObject . PHP_EOL;
73$unserializedExceptionObject = unserialize($serializedExceptionObject);
74echo "デシリアライズ後のメッセージ: " . $unserializedExceptionObject->getMessage() . PHP_EOL;
75// MyExceptionChildの__wakeupは呼び出されないため、additionalInfoは変更されません。
76echo "デシリアライズ後の追加情報: " . $unserializedExceptionObject->additionalInfo . PHP_EOL;
77
78echo PHP_EOL;
79echo "補足: 現在のPHPバージョン (" . PHP_VERSION . ") では、Exceptionを継承したクラスの __wakeup() メソッドは" . PHP_EOL;
80echo "unserialize() 時に自動的に呼び出されないように変更されています。" . PHP_EOL;
81echo "これは、`__wakeup`メソッドが悪用される可能性のあるデシリアライズ時の脆弱性に対し、" . PHP_EOL;
82echo "PHPが内部的にその実行を「回避」しているためです。" . PHP_EOL;

PHPの__wakeupメソッドは、シリアライズされたオブジェクトがunserialize()関数によって復元（デシリアライズ）される直前に自動的に呼び出される特別なメソッドです。このメソッドは引数を取らず、戻り値もありません。通常、__wakeupは、デシリアライズ後にオブジェクトの内部状態を適切に初期化したり、必要な準備処理を実行したりするために利用されます。

しかし、PHP 7.0以降のバージョンでは、Exceptionクラスとその子孫クラスにおける__wakeupメソッドの挙動が変更されました。具体的には、Exceptionを継承したクラスのオブジェクトをデシリアライズしても、定義されている__wakeupメソッドは自動的に呼び出されなくなっています。

この変更は、デシリアライズ処理を悪用したセキュリティ上の脆弱性、例えば悪意のあるデータを通じて意図しないコードが実行されるリスクを「回避」することを目的としています。サンプルコードでは、通常のクラスでは__wakeupが呼び出されてデータが変更されるのに対し、Exceptionを継承したクラスでは__wakeupが呼び出されず、データが変更されないことが示されています。これは、PHPが内部的にセキュリティリスクを軽減するために導入された重要な挙動です。