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

Copy
1<?php
2
3use Random\Engine\Mt19937;
4use Random\Randomizer;
5use Random\Engine;
6
7/**
8 * Random\Randomizer を継承したカスタムクラス。
9 * このクラスは、php.ini の `serialize_precision` 設定の影響を実演するために、
10 * 浮動小数点数プロパティを保持し、その値を `__serialize` メソッドでシリアライズ対象に含めます。
11 *
12 * システムエンジニアを目指す初心者の方へ:
13 * - `__serialize` メソッドは、オブジェクトを `serialize()` 関数で文字列に変換する際に、
14 *   PHP によって自動的に呼び出されるマジックメソッドです。
15 * - このメソッドは、オブジェクトの状態を表す配列を返す必要があります。
16 * - 返された配列が、実際のシリアライズ対象となります。
17 * - php.ini の `serialize_precision` 設定は、浮動小数点数をシリアライズする際の
18 *   文字列変換の精度（小数点以下の桁数）を決定します。このサンプルではその影響を示します。
19 */
20class CustomRandomizerWithFloat extends Randomizer
21{
22    /**
23     * @var float 浮動小数点数を含むプロパティ。`serialize_precision` のデモンストレーション用。
24     */
25    private float $demoFloatValue;
26
27    /**
28     * コンストラクタ。親クラス `Randomizer` を初期化し、デモ用の浮動小数点数を設定します。
29     *
30     * @param Random\Engine|null $engine 乱数エンジン。null の場合はデフォルトエンジンを使用。
31     */
32    public function __construct(?Engine $engine = null)
33    {
34        parent::__construct($engine);
35        // シリアライズ精度を示すため、精度が高い浮動小数点数を設定
36        $this->demoFloatValue = 123.4567890123456789;
37    }
38
39    /**
40     * オブジェクトがシリアライズされる際に呼び出されるマジックメソッド。
41     *
42     * このメソッドが返す配列が `serialize()` 関数によってシリアライズされます。
43     * ここで `demoFloatValue` を含めることで、`serialize_precision` の影響を確認できます。
44     *
45     * @return array シリアライズされるべきオブジェクトの状態を表す配列。
46     */
47    public function __serialize(): array
48    {
49        // 親クラス `Randomizer` の内部状態 (乱数エンジン) を取得し、シリアライズします。
50        // `getEngine()` は `protected` メソッドなので、継承クラスからアクセス可能です。
51        // エンジンオブジェクト自体もシリアライズ可能である必要があります。
52        $engineData = serialize($this->getEngine());
53
54        // 親クラスのエンジン状態と、このクラス独自の浮動小数点数を結合して返します。
55        // `generated_float_for_demo` は、シリアライズ時に生成された乱数であり、
56        // `serialize_precision` の影響を示すためだけに含まれています。
57        return [
58            'engine_serialized_data' => $engineData,
59            'my_custom_float_value' => $this->demoFloatValue,
60            'generated_float_for_demo' => $this->getFloat(),
61        ];
62    }
63
64    /**
65     * オブジェクトがデシリアライズされる際に呼び出されるマジックメソッド。
66     *
67     * `__serialize` が返した配列からオブジェクトの状態を復元します。
68     *
69     * @param array $data `__serialize` が返した配列。
70     */
71    public function __unserialize(array $data): void
72    {
73        // シリアライズされたエンジンデータをデシリアライズして復元
74        $restoredEngine = unserialize($data['engine_serialized_data']);
75
76        // 親クラス `Randomizer` のコンストラクタを呼び出してエンジンを再設定します。
77        // これにより、親クラスの乱数生成器が元の状態に戻ります。
78        parent::__construct($restoredEngine);
79
80        // このクラス独自の浮動小数点数プロパティを復元
81        $this->demoFloatValue = $data['my_custom_float_value'];
82        // 'generated_float_for_demo' は一時的な値なので、ここでは復元しません。
83    }
84
85    /**
86     * デモ用の浮動小数点数を取得するゲッター。
87     *
88     * @return float
89     */
90    public function getDemoFloatValue(): float
91    {
92        return $this->demoFloatValue;
93    }
94}
95
96// -----------------------------------------------------------------------------
97// サンプルコード実行部分
98// -----------------------------------------------------------------------------
99
100echo "--- CustomRandomizerWithFloat クラスのシリアライズ例 ---" . PHP_EOL . PHP_EOL;
101
102// 乱数エンジンを指定してCustomRandomizerWithFloatのインスタンスを作成
103$originalRandomizer = new CustomRandomizerWithFloat(new Mt19937(42));
104
105echo "元のオブジェクトのデモ浮動小数点数: " . sprintf('%.18f', $originalRandomizer->getDemoFloatValue()) . PHP_EOL;
106echo "元のオブジェクトが生成する乱数:    " . sprintf('%.18f', $originalRandomizer->getFloat()) . PHP_EOL;
107echo "----------------------------------------------------" . PHP_EOL;
108
109// php.ini の `serialize_precision` を一時的に変更して、シリアライズ結果の違いを観察します。
110// `ini_set` は実行時に設定を変更できます。`serialize_precision` は `serialize()` 関数が
111// 呼び出される前に適用されている必要があります。
112
113echo "serialize_precision = -1 (デフォルト、最高精度) の場合:" . PHP_EOL;
114// 現在の `serialize_precision` 設定を一時的に保存
115$originalPrecision = ini_get('serialize_precision');
116// `serialize_precision` を -1 (最高精度) に設定
117ini_set('serialize_precision', '-1');
118$serializedFullPrecision = serialize($originalRandomizer);
119ini_set('serialize_precision', $originalPrecision); // 設定を元に戻す
120
121echo "シリアライズされたデータ:" . PHP_EOL;
122echo $serializedFullPrecision . PHP_EOL . PHP_EOL;
123
124$restoredFullPrecision = unserialize($serializedFullPrecision);
125echo "デシリアライズ後のデモ浮動小数点数 (フル精度): " . sprintf('%.18f', $restoredFullPrecision->getDemoFloatValue()) . PHP_EOL;
126echo "デシリアライズ後、同じシードで生成される乱数:  " . sprintf('%.18f', $restoredFullPrecision->getFloat()) . PHP_EOL;
127echo "----------------------------------------------------" . PHP_EOL;
128
129
130echo "serialize_precision = 4 の場合 (小数点以下4桁に丸められる):" . PHP_EOL;
131$originalPrecision = ini_get('serialize_precision');
132ini_set('serialize_precision', '4');
133$serializedLimitedPrecision = serialize($originalRandomizer);
134ini_set('serialize_precision', $originalPrecision); // 設定を元に戻す
135
136echo "シリアライズされたデータ:" . PHP_EOL;
137echo $serializedLimitedPrecision . PHP_EOL . PHP_EOL;
138
139$restoredLimitedPrecision = unserialize($serializedLimitedPrecision);
140echo "デシリアライズ後のデモ浮動小数点数 (制限精度): " . sprintf('%.18f', $restoredLimitedPrecision->getDemoFloatValue()) . PHP_EOL;
141echo "デシリアライズ後、同じシードで生成される乱数:  " . sprintf('%.18f', $restoredLimitedPrecision->getFloat()) . PHP_EOL;
142echo "----------------------------------------------------" . PHP_EOL;
143
144echo "補足: `serialize_precision`は、浮動小数点数がシリアライズ文字列に変換される際の桁数を制御します。" . PHP_EOL;
145echo "これにより、デシリアライズ後に元の精度が失われる可能性があるため、注意が必要です。" . PHP_EOL;
146echo "この例では、シリアライズされたデータの `my_custom_float_value` と `generated_float_for_demo` の部分で" . PHP_EOL;
147echo "浮動小数点数の表記桁数に違いが現れることを確認できます。" . PHP_EOL;
148

PHPのRandom\Randomizer::__serializeメソッドは、オブジェクトをserialize()関数で文字列に変換する際に自動的に呼び出される特別なマジックメソッドです。このメソッドは引数を受け取らず、オブジェクトの内部状態を表す配列を返す役割を持ち、返された配列の内容が実際のシリアライズ対象となります。

サンプルコードでは、Random\Randomizerを継承したCustomRandomizerWithFloatクラスがこの__serializeメソッドをオーバーライドしています。これにより、親クラスの乱数エンジンの状態に加えて、自身が持つ浮動小数点数プロパティをシリアライズ対象の配列に含めています。このコードの重要なポイントは、php.iniのserialize_precision設定が浮動小数点数のシリアライズ精度に与える影響を示すことです。

serialize_precisionは、浮動小数点数をシリアライズ文字列に変換する際の小数点以下の桁数を制御します。サンプルでは、この設定を「-1」（最高精度）と「4」（小数点以下4桁に丸める）に変更してシリアライズを実行しています。これにより、同じ浮動小数点数がserialize()によってどのように表現されるか、そしてデシリアライズ後に元の精度が維持されるか、または失われるかが比較できるようになっています。浮動小数点数を含むオブジェクトをシリアライズする際は、この設定に注意が必要です。

Copy
1<?php
2
3// Random\Randomizer::__serialize メソッドの使用例
4// このメソッドは、RandomizerオブジェクトがPHPのシリアライズ機構によってシリアライズされる際に
5// 内部的に呼び出され、オブジェクトの状態を表す配列を返します。
6// ここでは、その戻り値を直接取得し、JSON形式に変換する例を示します。
7
8// Random\Randomizer クラスは PHP 8.2 で導入されました。
9// それ以前のバージョンではこのクラスは存在しません。
10if (!class_exists('Random\Randomizer')) {
11    echo "PHP 8.2 またはそれ以降のバージョンが必要です。\n";
12    exit(1);
13}
14
15/**
16 * Randomizerオブジェクトの内部状態をシリアライズし、JSON形式で出力します。
17 *
18 * Random\Randomizer::__serialize メソッドは、オブジェクトの状態を配列として返します。
19 * この配列を直接 JSON に変換することで、キーワード「php serialize to json」と
20 * メソッドの戻り値を関連付けています。
21 *
22 * @return void
23 */
24function displayRandomizerStateAsJson(): void
25{
26    // Random\Randomizer の新しいインスタンスを作成します。
27    // デフォルトのアルゴリズム (Random\Engine\Secure) が使用されます。
28    $randomizer = new Random\Randomizer();
29
30    // Random\Randomizer::__serialize メソッドを呼び出し、
31    // オブジェクトの内部状態を表す配列を取得します。
32    // 注意: 通常、__serialize マジックメソッドは serialize() 関数によって
33    //       内部的に呼び出されるもので、直接呼び出すことは一般的ではありません。
34    //       しかし、この例ではメソッドの戻り値（配列）とキーワードの関連性を示すため、
35    //       明示的に呼び出しています。
36    $serializedStateArray = $randomizer->__serialize();
37
38    // 取得した配列をJSON形式に変換します。
39    // JSON_PRETTY_PRINT は出力を整形し、JSON_UNESCAPED_UNICODE はマルチバイト文字をそのまま表示します。
40    $jsonOutput = json_encode($serializedStateArray, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
41
42    if ($jsonOutput === false) {
43        echo "エラー: 配列をJSONにエンコードできませんでした。\n";
44        return;
45    }
46
47    // JSON形式の出力を表示します。
48    echo "Random\\Randomizerオブジェクトのシリアライズされた状態 (JSON形式):\n";
49    echo $jsonOutput . "\n";
50}
51
52// 関数を実行して、Randomizerオブジェクトの状態をJSON形式で出力します。
53displayRandomizerStateAsJson();
54

このサンプルコードは、PHP 8.2以降で導入されたRandom\Randomizerクラスの__serializeメソッドの働きと、その戻り値であるオブジェクトの状態をJSON形式で出力する方法を具体的に示しています。Random\Randomizer::__serializeメソッドは引数を受け取らず、Randomizerオブジェクトの現在の内部状態を配列として返します。通常、このメソッドはPHPのserialize()関数によってオブジェクトがシリアライズされる際に、システムによって自動的に呼び出される「マジックメソッド」ですが、この例ではメソッドの戻り値がどのような構造の配列であるかを示すために、明示的に呼び出しています。

コードでは、まずRandom\Randomizerのインスタンスを作成し、次にその__serializeメソッドを呼び出すことで、オブジェクトの状態を表す配列を取得します。この取得した配列を、json_encode関数を用いてJSON形式の文字列に変換しています。JSON_PRETTY_PRINTなどのオプションを使うことで、整形された読みやすいJSONが出力されます。このように、オブジェクトのシリアライズ可能な状態を配列として取得し、それをJSONに変換する過程を通して、「php serialize to json」というキーワードが示す具体的な実装方法を学ぶことができます。

Copy
1<?php
2
3/**
4 * Random\Randomizer::__serialize メソッドは、PHPのserialize()関数がオブジェクトを
5 * バイト列に変換する際に、そのオブジェクトの内部状態を取得するために内部的に呼び出されます。
6 * 開発者がこのメソッドを直接呼び出すことは通常ありません。
7 *
8 * このサンプルコードでは、Random\Randomizerオブジェクトをシリアライズし、その後アンシリアライズして、
9 * 乱数生成器の状態が正しく保存・復元されることを示します。
10 */
11function demonstrateRandomizerSerialization(): void
12{
13    // 1. 最初の Randomizer オブジェクトを作成します。
14    // 特定のエンジンとシードを指定することで、乱数生成のシーケンスを再現可能にします。
15    $seed = 42; // シードを固定
16    $initialRandomizer = new Random\Randomizer(new Random\Engine\Xoshiro256StarStar($seed));
17
18    echo "--- 最初の Randomizer オブジェクトの状態 ---\n";
19    $initialNum1 = $initialRandomizer->getInt(1, 100);
20    echo "最初の乱数: " . $initialNum1 . "\n";
21    $initialNum2 = $initialRandomizer->getInt(1, 100);
22    echo "次の乱数: " . $initialNum2 . "\n\n";
23
24    // 2. オブジェクトをシリアライズします。
25    // PHPのserialize()関数が内部でRandom\Randomizer::__serializeを呼び出し、
26    // オブジェクトの現在の状態を表す情報をバイト列に変換します。
27    $serializedData = serialize($initialRandomizer);
28    echo "--- シリアライズされたデータ ---\n";
29    // バイト列を画面表示用にBase64エンコードします
30    echo "シリアライズされたバイト列 (Base64エンコード): " . base64_encode($serializedData) . "\n\n";
31
32    // 3. シリアライズされたデータをアンシリアライズして、新しいオブジェクトを復元します。
33    // PHPのunserialize()関数が内部でRandom\Randomizer::__unserializeを呼び出し、
34    // バイト列からオブジェクトの状態を復元し、新しいRandomizerオブジェクトを生成します。
35    /** @var Random\Randomizer $restoredRandomizer */
36    $restoredRandomizer = unserialize($serializedData);
37
38    echo "--- 復元された Randomizer オブジェクトの状態 ---\n";
39    // 復元されたオブジェクトから乱数を生成します。
40    // シリアライズ前と同じシーケンスが再現されるはずです。
41    $restoredNum1 = $restoredRandomizer->getInt(1, 100);
42    echo "復元後の最初の乱数: " . $restoredNum1 . "\n";
43    $restoredNum2 = $restoredRandomizer->getInt(1, 100);
44    echo "復元後の次の乱数: " . $restoredNum2 . "\n\n";
45
46    // 4. 状態が正しく復元されたことを確認します。
47    echo "--- 検証 ---\n";
48    if ($initialNum1 === $restoredNum1 && $initialNum2 === $restoredNum2) {
49        echo "✅ シリアライズとアンシリアライズにより、Randomizerの状態が正しく復元されました。\n";
50        echo "   最初のオブジェクトと復元されたオブジェクトは同じ乱数シーケンスを生成します。\n";
51    } else {
52        echo "❌ シリアライズまたはアンシリアライズ中にエラーが発生しました。\n";
53    }
54}
55
56// 関数を実行してデモンストレーションを開始します。
57demonstrateRandomizerSerialization();

Random\Randomizer::__serializeメソッドは、PHPのserialize()関数がオブジェクトをバイト列に変換する際に、そのオブジェクトの内部状態を配列として取得するために内部的に呼び出される特別なメソッドです。開発者がこのメソッドを直接呼び出すことは通常ありません。引数はなく、オブジェクトの現在の状態を表す情報を格納した配列を戻り値として返します。

この機能は、オブジェクトの現在の状態を保存し、後でまったく同じ状態に復元したい場合に利用されます。例えば、乱数生成器であるRandom\Randomizerオブジェクトの場合、乱数生成のシード値を含めた現在の内部状態を保存・復元することで、常に同じ乱数シーケンスを再現することが可能になります。

サンプルコードでは、まずRandom\Randomizerオブジェクトを作成し、いくつかの乱数を生成してその時点の状態を確認します。次に、serialize()関数を使ってこのオブジェクトをバイト列に変換します。この際、内部で__serializeメソッドが呼び出され、オブジェクトの現在の状態に関する情報がバイト列に含まれます。最後に、unserialize()関数を使ってそのバイト列から新しいRandom\Randomizerオブジェクトを復元します。復元されたオブジェクトから乱数を生成すると、シリアライズされる前と同じ乱数シーケンスが再現されることを確認でき、オブジェクトの状態が正しく保存・復元されたことが示されます。