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

Copy
1<?php
2
3// Random\Engine\PcgOneseq128XslRr64 は PHP 8.2 以降で利用可能です。
4// それ以前のバージョンで実行するとエラーが発生します。
5
6/**
7 * Random\Engine\PcgOneseq128XslRr64 エンジンのシリアライズとデシリアライズの例。
8 *
9 * このクラスのインスタンスをシリアライズし、デシリアライズして
10 * 乱数生成の状態が正しく復元されることを確認します。
11 *
12 * Random\Engine\PcgOneseq128XslRr64::__serialize メソッドは、
13 * オブジェクトが serialize() 関数によってシリアライズされる際に、
14 * その内部状態を配列として返すためにPHPの内部で自動的に呼び出されます。
15 * 開発者がこのメソッドを直接呼び出すことは通常ありません。
16 *
17 * php.ini の設定項目 'serialize_precision' は、浮動小数点数をシリアライズする際の
18 * 精度に影響を与えます。Random\Engine クラス自体は通常、浮動小数点数ではなく
19 * 整数ベースの状態を扱うため、この設定が直接的な結果に影響を与えることは
20 * 少ないですが、serialize() 関数を使用する全てのデータに適用されるため、
21 * オブジェクトのシリアライズプロセスの一部として関連キーワードとしてここで示します。
22 */
23final class PcgEngineSerializationExample
24{
25    public static function run(): void
26    {
27        echo "--- Random\\Engine\\PcgOneseq128XslRr64 のシリアライズ例 ---\n\n";
28
29        // 初期シード値を持つPcgOneseq128XslRr64エンジンを作成
30        // 引数には128ビットの整数、または文字列形式の128ビット整数を指定します。
31        // ここでは例として128ビットのシード値を指定しています。
32        $initialSeed = '0x1234567890abcdef1234567890abcdef';
33        $originalEngine = new Random\Engine\PcgOneseq128XslRr64($initialSeed);
34
35        // 最初の乱数を生成
36        echo "元のエンジンで最初の乱数を生成: " . $originalEngine->generate() . "\n";
37        // 次の乱数を生成し、シリアライズ後の比較のために保存
38        $nextValueBeforeSerialize = $originalEngine->generate();
39        echo "元のエンジンで次の乱数を生成 (シリアライズ前): " . $nextValueBeforeSerialize . "\n\n";
40
41        // serialize_precision の設定を一時的に変更
42        // この設定は主に浮動小数点数のシリアライズ精度に影響します。
43        // Random\Engine の内部状態が整数ベースの場合、直接的な影響は小さいですが、
44        // serialize() 関数が呼び出される際に考慮されるグローバル設定です。
45        $originalSerializePrecision = ini_get('serialize_precision');
46        ini_set('serialize_precision', '17'); // 浮動小数点数の標準的な精度
47        echo "ini_set('serialize_precision', '17') を適用\n";
48        echo "現在の serialize_precision: " . ini_get('serialize_precision') . "\n\n";
49
50        // エンジンをシリアライズ
51        // この時、PHPの内部で Random\Engine\PcgOneseq128XslRr64::__serialize メソッドが
52        // 自動的に呼び出され、エンジンの現在の状態が配列として取得され、シリアライズされます。
53        $serializedEngine = serialize($originalEngine);
54        echo "シリアライズされたエンジン (最初の100文字):\n";
55        echo substr($serializedEngine, 0, 100) . "...\n\n";
56
57        // serialize_precision を元の設定に戻す
58        ini_set('serialize_precision', $originalSerializePrecision);
59        echo "ini_set('serialize_precision', '{$originalSerializePrecision}') に戻しました\n";
60        echo "現在の serialize_precision: " . ini_get('serialize_precision') . "\n\n";
61
62        // シリアライズされたデータからエンジンをデシリアライズ
63        // これにより、Random\Engine\PcgOneseq128XslRr64 の状態が復元されます。
64        // PHP 8.1以前のバージョンの場合、マジックメソッド__unserializeは非推奨ですが、
65        // PHP 8.2以降のRandom\Engineでは内部的に安全なシリアライズメカニズムを使用します。
66        $deserializedEngine = unserialize($serializedEngine);
67
68        // デシリアライズされたエンジンが元のエンジンと同じ状態から乱数を生成することを確認
69        $nextValueAfterDeserialize = $deserializedEngine->generate();
70        echo "デシリアライズされたエンジンで次の乱数を生成 (デシリアライズ後): " . $nextValueAfterDeserialize . "\n\n";
71
72        // 結果の比較
73        if ($nextValueBeforeSerialize === $nextValueAfterDeserialize) {
74            echo "乱数生成が継続され、シリアライズ/デシリアライズが成功しました。\n";
75        } else {
76            echo "エラー: シリアライズ/デシリアライズ後に乱数生成の状態が一致しません。\n";
77        }
78    }
79}
80
81// クラスを実行
82PcgEngineSerializationExample::run();

PHP 8.2以降で利用可能なRandom\Engine\PcgOneseq128XslRr64クラスの__serializeメソッドは、このオブジェクトがPHPのserialize()関数によって文字列形式に変換される際、その内部状態を配列として取得するために自動的に呼び出される特別なメソッドです。開発者がこのメソッドを直接呼び出すことは通常ありません。このメソッドは引数を取らず、現在のオブジェクトの状態を表現する連想配列を戻り値として返します。この配列は、後にunserialize()関数によってオブジェクトが復元される際に利用され、乱数エンジンの状態を正確に再現するために不可欠です。

サンプルコードでは、PcgOneseq128XslRr64エンジンのインスタンスを作成し、乱数を生成してその状態を進めた後でシリアライズしています。これにより、__serializeが内部的に呼び出され、エンジンの状態が保存されます。その後、保存されたデータからオブジェクトをデシリアライズすることで、元のエンジンの状態が完全に復元され、同じ乱数シーケンスが継続して生成されることを検証しています。php.iniのserialize_precision設定は、serialize()関数が浮動小数点数を処理する際の精度に影響しますが、Random\Engineの内部状態は主に整数であるため、この設定が直接的な結果に与える影響は少ないものの、シリアライズ処理全体に適用される関連キーワードとして示されています。

Copy
1<?php
2
3/**
4 * PHP 8.2 以降で動作します。
5 *
6 * Random\Engine\PcgOneseq128XslRr64 クラスの __serialize および __unserialize メソッドの
7 * 動作を示すサンプルコードです。
8 *
9 * PHP 8 以降では、カスタムシリアライズに __serialize/__unserialize マジックメソッドが推奨されます。
10 * - serialize() 関数がオブジェクトに適用されると、__serialize メソッドが自動的に呼び出され、
11 *   その戻り値（配列）がオブジェクトのシリアライズデータとして使用されます。
12 * - unserialize() 関数がシリアライズデータからオブジェクトを復元する際、
13 *   新しく作成されたオブジェクトの __unserialize メソッドが自動的に呼び出され、
14 *   シリアライズされた配列データが引数として渡され、オブジェクトの状態が復元されます。
15 */
16
17use Random\Engine\PcgOneseq128XslRr64;
18use Random\Randomizer;
19
20// 1. Random\Engine\PcgOneseq128XslRr64 インスタンスを作成します。
21$engine = new PcgOneseq128XslRr64();
22$randomizer = new Randomizer($engine);
23
24echo "--- 初期状態の乱数エンジン ---" . PHP_EOL;
25echo "最初の乱数: " . $randomizer->getInt(1, 100) . PHP_EOL;
26echo "二番目の乱数: " . $randomizer->getInt(1, 100) . PHP_EOL;
27
28// 2. オブジェクトの状態を保存するため、serialize() 関数でシリアライズします。
29//    この時、内部的に Random\Engine\PcgOneseq128XslRr64::__serialize() が呼び出されます。
30echo PHP_EOL . "--- オブジェクトのシリアライズ ---" . PHP_EOL;
31$serializedEngine = serialize($engine);
32echo "シリアライズされた文字列: " . $serializedEngine . PHP_EOL;
33
34// 3. シリアライズされた文字列からオブジェクトの状態を復元（デシリアライズ）します。
35//    この時、内部的に Random\Engine\PcgOneseq128XslRr64::__unserialize() が呼び出されます。
36echo PHP_EOL . "--- オブジェクトのデシリアライズ ---" . PHP_EOL;
37$newEngine = unserialize($serializedEngine);
38$newRandomizer = new Randomizer($newEngine);
39
40echo "デシリアライズされたオブジェクトで乱数生成:" . PHP_EOL;
41// 元のオブジェクトが中断した状態から乱数生成が再開されることを確認します。
42echo "三番目の乱数: " . $newRandomizer->getInt(1, 100) . PHP_EOL;
43echo "四番目の乱数: " . $newRandomizer->getInt(1, 100) . PHP_EOL;
44
45echo PHP_EOL . "--- 元のオブジェクトでの乱数生成を継続 ---" . PHP_EOL;
46// 元のオブジェクトも引き続き利用可能です。
47echo "元のオブジェクトで三番目の乱数: " . $randomizer->getInt(1, 100) . PHP_EOL;
48

Random\Engine\PcgOneseq128XslRr64::__serializeは、PHP 8以降でオブジェクトのカスタムシリアライズに推奨されるマジックメソッドです。このメソッドは、serialize()関数を使ってオブジェクトを文字列形式に変換（シリアライズ）する際に、オブジェクトがその内部状態をどのように保存するかを定義するために利用されます。

引数はなく、現在のオブジェクトの状態を表す連想配列（array）を戻り値として返します。この戻り値の配列が、オブジェクトのシリアライズデータとして使用されます。例えば、乱数エンジンのような内部状態を持つオブジェクトを一時的に保存し、後でその状態から正確に復元したい場合に非常に有効です。

具体的には、serialize()がオブジェクトに適用されると、この__serializeメソッドが自動的に呼び出され、返された配列データが保持されます。その後、unserialize()関数でこのデータからオブジェクトを復元する際には、対応する__unserializeメソッドが呼び出され、保存された配列データを使って元の状態が再現されます。これにより、シリアライズされた乱数エンジンは、中断した位置から乱数生成を再開できるようになります。サンプルコードは、乱数エンジンの状態を保存し、復元することで、乱数生成が継続される様子を示しています。