【PHP8.x】__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 * 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メソッドが実行され、カスタムロジックが適用されたことを視覚的に確認できます。これは、デシリアライズ時にオブジェクトの特定の初期化や調整が必要な場合に特に有用です。