【PHP8.x】Random\Engine\Xoshiro256StarStar::__unserialize()メソッドの使い方

Copy
1<?php
2
3// このサンプルコードは PHP 8.2 以降で利用可能な Random\Engine\Xoshiro256StarStar クラスを使用します。
4// そのため、PHP 8.2 未満の環境ではエラーが発生します。
5if (version_compare(PHP_VERSION, '8.2.0', '<')) {
6    echo "エラー: このサンプルコードは PHP 8.2 以降が必要です。\n";
7    exit(1);
8}
9
10use Random\Engine\Xoshiro256StarStar;
11use Random\Randomizer;
12
13// --- Random\Engine\Xoshiro256StarStar のシリアライズとデシリアライズの例 ---
14
15echo "--- PHP の unserialize と Random\\Engine\\Xoshiro256StarStar の使用例 ---\n\n";
16
17// 1. 元の乱数エンジンと、それを使用する乱数生成器を作成します。
18//    Xoshiro256StarStar は、高品質な疑似乱数を生成するための内部状態を管理します。
19$originalEngine = new Xoshiro256StarStar();
20$originalRandomizer = new Randomizer($originalEngine);
21
22echo "元の乱数生成器で最初の3つの乱数を生成します (初期状態のエンジンを使用)。\n";
23echo "この操作により、エンジンの内部状態が進行します。\n";
24$originalNumbersBeforeSerialization = [];
25for ($i = 0; $i < 3; $i++) {
26    $num = $originalRandomizer->getInt(0, 100);
27    $originalNumbersBeforeSerialization[] = $num;
28    echo " - " . $num . "\n";
29}
30echo "\n";
31
32// 2. 現在の乱数エンジンオブジェクトをシリアライズします。
33//    シリアライズは、オブジェクトの現在の状態を文字列形式に変換するプロセスです。
34//    これにより、オブジェクトの状態をファイルに保存したり、ネットワーク経由で転送したりできます。
35echo "乱数エンジンをシリアライズします (現在の内部状態を文字列として保存)。\n";
36$serializedEngine = serialize($originalEngine);
37echo "シリアライズされたデータ例 (一部): " . substr($serializedEngine, 0, 70) . "...\n\n";
38
39// 3. シリアライズされたデータから乱数エンジンオブジェクトをデシリアライズします。
40//    デシリアライズは、シリアライズされた文字列から元のオブジェクトの状態を復元するプロセスです。
41//    この時、`unserialize()` 関数が内部的に `Random\Engine\Xoshiro256StarStar::__unserialize()` メソッドを呼び出し、
42//    `$serializedEngine` のデータに基づいてオブジェクトの内部状態が正確に再構築されます。
43echo "シリアライズされたデータから乱数エンジンをデシリアライズします。\n";
44echo "この操作中に `Random\\Engine\\Xoshiro256StarStar::__unserialize` が内部的に呼び出されます。\n";
45$unserializedEngine = unserialize($serializedEngine);
46
47// 復元されたオブジェクトが期待される型であるかを確認します。
48if ($unserializedEngine instanceof Xoshiro256StarStar) {
49    echo "デシリアライズ成功: `Random\\Engine\\Xoshiro256StarStar` のインスタンスが復元されました。\n\n";
50
51    // 4. 復元されたエンジンを使用して新しい乱数生成器を作成し、乱数を生成します。
52    //    もし `__unserialize` が正しく機能していれば、元のエンジンと復元されたエンジンは
53    //    シリアライズ時点での状態から同じ乱数シーケンスを生成し続けるはずです。
54    $restoredRandomizer = new Randomizer($unserializedEngine);
55
56    echo "元の乱数生成器 (シリアライズ後) で生成する次の3つの乱数:\n";
57    $originalNumbersAfterSerialization = [];
58    for ($i = 0; $i < 3; $i++) {
59        $num = $originalRandomizer->getInt(0, 100);
60        $originalNumbersAfterSerialization[] = $num;
61        echo " - " . $num . "\n";
62    }
63    echo "\n";
64
65    echo "復元された乱数生成器 (デシリアライズ後) で生成する次の3つの乱数:\n";
66    $restoredNumbers = [];
67    for ($i = 0; $i < 3; $i++) {
68        $num = $restoredRandomizer->getInt(0, 100);
69        $restoredNumbers[] = $num;
70        echo " - " . $num . "\n";
71    }
72    echo "\n";
73
74    // 5. 生成された乱数シーケンスを比較し、`__unserialize` が正常に機能したかを確認します。
75    //    両者の乱数シーケンスが完全に一致すれば、オブジェクトの状態が正確に保存・復元されたことになります。
76    echo "乱数シーケンスの連続性を確認します:\n";
77    if ($originalNumbersAfterSerialization === $restoredNumbers) {
78        echo "結果: 乱数シーケンスは維持されています。`__unserialize` が正常に動作し、オブジェクトの状態が正しく復元されました。\n";
79    } else {
80        echo "結果: 乱数シーケンスが一致しません。オブジェクトの状態が正しく復元されなかった可能性があります。\n";
81    }
82
83} else {
84    echo "エラー: デシリアライズに失敗しました。期待される `Random\\Engine\\Xoshiro256StarStar` のインスタンスではありませんでした。\n";
85}

PHP 8以降で導入されたRandom\Engine\Xoshiro256StarStar::__unserializeメソッドは、PHPの組み込み関数unserialize()が、このクラスのオブジェクトを文字列から復元する際に内部的に呼び出す特殊なメソッドです。Random\Engine\Xoshiro256StarStarは、高品質な疑似乱数を生成するためのエンジンであり、その内部状態を管理します。

オブジェクトの「シリアライズ」とは、そのオブジェクトの現在の状態を保存可能な形式（通常は文字列）に変換するプロセスです。逆に「デシリアライズ」とは、その文字列から元のオブジェクトの状態を正確に復元するプロセスを指します。この__unserializeメソッドは、デシリアライズ時に、引数$dataとして渡される状態情報を含む配列をもとに、オブジェクト自身の内部状態を再構築する役割を担います。これにより、乱数エンジンがシリアライズされた時点の続きから、同じ乱数シーケンスを生成できるようになります。

サンプルコードでは、まず元の乱数エンジンでいくつかの乱数を生成し、その後のエンジンの状態をシリアライズしています。次に、unserialize()関数を使ってその文字列から新しい乱数エンジンオブジェクトを復元しますが、この時、Random\Engine\Xoshiro256StarStar::__unserializeが自動的に呼び出され、引数$dataを用いてエンジンの状態が正確に再現されます。結果として、元のエンジンと復元されたエンジンの両方が、シリアライズ時点から同一の乱数シーケンスを生成し続けることを確認できます。このメソッドはvoidを返すため、直接的な戻り値はありませんが、呼び出されたオブジェクトの内部状態が更新されます。なお、このクラスはPHP 8.2以降で利用可能です。

Copy
1<?php
2
3/**
4 * このMyDataClassは、PHPの__serialize()と__unserialize()マジックメソッドを
5 * 使用してオブジェクトのシリアライズ（直列化）と非シリアライズ（復元）を
6 * カスタマイズする方法を示すための例です。
7 * Random\Engine\Xoshiro256StarStar::__unserialize も同様に、
8 * シリアライズされたデータ配列からオブジェクトの状態を復元するために
9 * 内部的に呼び出されます。
10 */
11class MyDataClass
12{
13    private string $itemName;
14    private int $itemCount;
15    private array $itemTags;
16
17    /**
18     * コンストラクタ
19     *
20     * @param string $itemName アイテム名
21     * @param int $itemCount アイテム数
22     * @param array $itemTags アイテムのタグ配列
23     */
24    public function __construct(string $itemName, int $itemCount, array $itemTags)
25    {
26        $this->itemName = $itemName;
27        $this->itemCount = $itemCount;
28        $this->itemTags = $itemTags;
29    }
30
31    /**
32     * オブジェクトが serialize() 関数によってシリアライズされる際に呼び出されます。
33     * 復元に必要なプロパティを配列として返します。
34     * PHP 8以降で推奨されるシリアライズ方法です。
35     *
36     * @return array シリアライズするデータ
37     */
38    public function __serialize(): array
39    {
40        // データのサイズを小さくするため、短いキー名を使用することがあります。
41        return [
42            'name' => $this->itemName,
43            'count' => $this->itemCount,
44            'tags' => $this->itemTags,
45        ];
46    }
47
48    /**
49     * シリアライズされたデータが unserialize() 関数によってオブジェクトに復元される際に呼び出されます。
50     * 引数 $data には __serialize() が返した配列が渡されます。
51     * このメソッドを使用して、オブジェクトのプロパティを再構築します。
52     *
53     * @param array $data シリアライズされたデータ配列
54     * @return void
55     */
56    public function __unserialize(array $data): void
57    {
58        // 渡されたデータを使用してオブジェクトのプロパティを設定します。
59        // データが存在しない場合のために、デフォルト値やエラーハンドリングを含めることが推奨されます。
60        $this->itemName = $data['name'] ?? 'Unknown Item';
61        $this->itemCount = $data['count'] ?? 0;
62        $this->itemTags = $data['tags'] ?? [];
63    }
64
65    /**
66     * オブジェクトの現在のデータを連想配列として取得します。
67     * 主にデモンストレーションとJSON変換のために使用します。
68     *
69     * @return array オブジェクトのデータ
70     */
71    public function getProperties(): array
72    {
73        return [
74            'name' => $this->itemName,
75            'count' => $this->itemCount,
76            'tags' => $this->itemTags,
77        ];
78    }
79}
80
81// --------------------------------------------------------------------------------
82// サンプルコード実行部分
83// --------------------------------------------------------------------------------
84
85// 1. 元のオブジェクトを作成します。
86$originalObject = new MyDataClass('PHP Manual', 1, ['programming', 'documentation', 'php8']);
87echo "--- 元のオブジェクトの状態 ---" . PHP_EOL;
88print_r($originalObject->getProperties());
89
90// 2. オブジェクトをシリアライズします。
91// この際、MyDataClass::__serialize() メソッドが自動的に呼び出されます。
92$serializedData = serialize($originalObject);
93echo PHP_EOL . "--- シリアライズされた文字列 ---" . PHP_EOL;
94echo $serializedData . PHP_EOL;
95
96// 3. シリアライズされた文字列を非シリアライズし、オブジェクトに復元します。
97// この際、MyDataClass::__unserialize(array $data) メソッドが自動的に呼び出され、
98// 復元されたオブジェクトのプロパティが設定されます。
99$restoredObject = unserialize($serializedData);
100
101echo PHP_EOL . "--- 非シリアライズされた（復元された）オブジェクトの状態 ---" . PHP_EOL;
102if ($restoredObject instanceof MyDataClass) {
103    print_r($restoredObject->getProperties());
104
105    // 4. 非シリアライズされたオブジェクトのデータをJSON形式に変換します。
106    // json_encode() は、通常オブジェクトのpublicプロパティや、
107    // JsonSerializableインターフェースを実装している場合はその内容をJSONに変換します。
108    // ここでは、getProperties() メソッドで取得した連想配列をJSONに変換します。
109    $jsonOutput = json_encode($restoredObject->getProperties(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
110    echo PHP_EOL . "--- JSON形式の出力 ---" . PHP_EOL;
111    echo $jsonOutput . PHP_EOL;
112} else {
113    echo "エラー: オブジェクトの復元に失敗しました。" . PHP_EOL;
114}

PHPの__unserializeメソッドは、serialize()関数によって文字列化されたオブジェクトのデータを、元のオブジェクトとして復元する際に自動的に呼び出される特別なメソッドです。システムエンジニアを目指す方にとって、オブジェクトの状態を保存し、後で再構築する「シリアライズ」の仕組みを理解することは重要です。

このメソッドはarray $dataという引数を受け取ります。この$dataには、オブジェクトをシリアライズする際に自動的に呼び出される__serialize()メソッドが返した配列のデータが渡されます。開発者は、この$data配列に含まれる情報を使って、オブジェクトの各プロパティ（属性）を適切に設定し直し、元の状態を再現します。メソッドの戻り値はvoidであり、このメソッド自体は値を返す必要はありません。

例えば、サンプルコードのMyDataClassでは、__unserializeメソッドが、シリアライズされたデータからアイテム名や数、タグといった情報を読み取り、それらを新しいMyDataClassオブジェクトのプロパティとして再設定しています。これにより、serialize()で文字列化されたデータから、unserialize()で完全に同じ状態のオブジェクトを作り出すことが可能になります。

Random\Engine\Xoshiro256StarStarのようなPHPの内部クラスでも、__unserializeは同様に、シリアライズされた乱数エンジンの状態を復元するために内部的に使用されています。このように、オブジェクトのシリアライズと非シリアライズの仕組みは、PHPアプリケーションでデータを永続化する上で広く利用されており、復元されたオブジェクトのデータをjson_encodeでJSON形式に変換することも一般的で、オンラインツールでのデバッグなどにも役立ちます。