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

Copy
1<?php
2
3/**
4 * このクラスは、__serializeマジックメソッドの実装例と、
5 * PHPのserialize_precision設定が浮動小数点数のシリアライズに
6 * どのように影響するかを示します。
7 *
8 * Random\Engine\Xoshiro256StarStar::__serialize メソッドも同様に、
9 * オブジェクトの内部状態（この場合は乱数エンジンの状態）を配列として返します。
10 * ここでは、浮動小数点数を含むカスタムオブジェクトを使用して、
11 * serialize_precision の効果をより明確に示します。
12 */
13class MyCustomSerializableObject
14{
15    private string $label;
16    private int $counter;
17    private float $dataValue;
18
19    /**
20     * コンストラクタ。オブジェクトのプロパティを初期化します。
21     *
22     * @param string $label オブジェクトの識別ラベル
23     * @param int $counter カウンター値
24     * @param float $dataValue シリアライズ精度が影響する浮動小数点数値
25     */
26    public function __construct(string $label, int $counter, float $dataValue)
27    {
28        $this->label = $label;
29        $this->counter = $counter;
30        $this->dataValue = $dataValue;
31    }
32
33    /**
34     * オブジェクトをシリアライズする際に呼び出されるマジックメソッド。
35     * このメソッドは、オブジェクトの内部状態を表現する配列を返します。
36     *
37     * Random\Engine\Xoshiro256StarStar::__serialize も、
38     * その乱数生成エンジンの内部状態を配列として返します。
39     *
40     * @return array オブジェクトのシリアライズ可能なプロパティの配列
41     */
42    public function __serialize(): array
43    {
44        // ここで返される配列の要素が serialize() 関数によって処理されます。
45        // dataValueが浮動小数点数なので、serialize_precisionの影響を受けます。
46        return [
47            'label' => $this->label,
48            'count' => $this->counter,
49            'value' => $this->dataValue,
50        ];
51    }
52
53    /**
54     * オブジェクトをアンシリアライズする際に呼び出されるマジックメソッド。
55     * __serialize メソッドが返した配列を受け取り、オブジェクトの状態を復元します。
56     *
57     * @param array $data __serialize によって提供されたデータ配列
58     */
59    public function __unserialize(array $data): void
60    {
61        $this->label = $data['label'];
62        $this->counter = $data['count'];
63        $this->dataValue = $data['value'];
64    }
65
66    /**
67     * オブジェクトの現在の状態を文字列として返します。
68     *
69     * @return string オブジェクトの状態を示す文字列
70     */
71    public function __toString(): string
72    {
73        return sprintf(
74            "Label: '%s', Counter: %d, Value: %.17f",
75            $this->label,
76            $this->counter,
77            $this->dataValue
78        );
79    }
80}
81
82// ----------------------------------------------------
83// serialize_precision 設定とシリアライズの結果の確認
84// ----------------------------------------------------
85
86// 元の serialize_precision の値を保存し、後で元に戻します
87$originalPrecision = ini_get('serialize_precision');
88
89$objectToSerialize = new MyCustomSerializableObject("Example A", 10, 123.4567890123456789);
90
91echo "--- デフォルトの serialize_precision (通常は17)でのシリアライズ ---\n";
92// serialize_precision の設定を確認
93echo "現在の serialize_precision: " . ini_get('serialize_precision') . "\n";
94
95$serializedDefault = serialize($objectToSerialize);
96$unserializedDefault = unserialize($serializedDefault);
97
98echo "元のオブジェクト: " . $objectToSerialize . "\n";
99echo "シリアライズ結果: " . $serializedDefault . "\n";
100echo "アンシリアライズ結果: " . $unserializedDefault . "\n\n";
101
102echo "--- serialize_precision を 5 に設定してシリアライズ ---\n";
103// serialize_precision を一時的に変更
104ini_set('serialize_precision', 5);
105echo "現在の serialize_precision: " . ini_get('serialize_precision') . "\n";
106
107$serializedLowPrecision = serialize($objectToSerialize);
108$unserializedLowPrecision = unserialize($serializedLowPrecision);
109
110echo "元のオブジェクト: " . $objectToSerialize . "\n";
111echo "シリアライズ結果: " . $serializedLowPrecision . "\n";
112echo "アンシリアライズ結果: " . $unserializedLowPrecision . "\n\n";
113
114echo "--- serialize_precision を 10 に設定してシリアライズ ---\n";
115// serialize_precision を別の値に変更
116ini_set('serialize_precision', 10);
117echo "現在の serialize_precision: " . ini_get('serialize_precision') . "\n";
118
119$serializedMediumPrecision = serialize($objectToSerialize);
120$unserializedMediumPrecision = unserialize($serializedMediumPrecision);
121
122echo "元のオブジェクト: " . $objectToSerialize . "\n";
123echo "シリアライズ結果: " . $serializedMediumPrecision . "\n";
124echo "アンシリアライズ結果: " . $unserializedMediumPrecision . "\n\n";
125
126// 設定を元の値に戻します
127ini_set('serialize_precision', $originalPrecision);
128
129?>

PHP 8のRandom\Engine\Xoshiro256StarStarクラスに存在する__serializeメソッドは、そのオブジェクトの内部状態を配列として返します。これは、PHPのserialize()関数によってオブジェクトを文字列形式に変換する際に自動的に呼び出される特別な「マジックメソッド」です。このメソッドは引数を受け取らず、オブジェクトのシリアライズ可能なプロパティを格納した配列を戻り値として返します。これにより、乱数エンジンの現在の状態（例えば、乱数生成のシード値や内部的な状態変数）を正確に保存し、後でその状態から乱数生成を再開できるようになります。

提供されたサンプルコードは、カスタムクラスMyCustomSerializableObjectを使用して__serializeマジックメソッドの一般的な動作を実演しています。このカスタムクラスでは、オブジェクトの識別ラベル、カウンター、そして浮動小数点数値の三つのプロパティを内部状態として持っています。__serializeメソッドはこれらのプロパティを連想配列として返すことで、serialize()関数がオブジェクトを文字列に変換できるようになっています。特に注目すべきは、浮動小数点数プロパティのシリアライズ結果がPHPの設定項目であるserialize_precisionによって変化する点です。この設定は、浮動小数点数を文字列に変換する際の有効桁数を制御するため、設定値が低いとシリアライズされた浮動小数点数の精度が失われ、アンシリアライズ後に元の値と異なる可能性が生じます。サンプルコードは、このserialize_precisionの値を変更しながらシリアライズとアンシリアライズを行い、その影響を具体的に示しています。

Copy
1<?php
2
3/**
4 * Random\Engine\Xoshiro256StarStar::__serialize メソッドの使用例を示します。
5 * このコードは PHP 8.2 以降で動作します。
6 * Random\Engine\Xoshiro256StarStar クラスは PHP 8.2 で導入されました。
7 */
8function demonstrateSerialization(): void
9{
10    echo "--- 1. 元の Random\\Engine\\Xoshiro256StarStar インスタンスの作成と乱数生成 ---\n";
11
12    // 新しい乱数エンジンインスタンスを生成します。
13    // 引数なしの場合、シードはシステムによって自動的に設定されます。
14    $originalEngine = new Random\Engine\Xoshiro256StarStar();
15
16    // 最初の乱数を生成し、エンジンの内部状態を変化させます。
17    echo "元のエンジンが生成した最初の乱数: " . $originalEngine->generate() . "\n";
18    // 2番目の乱数を生成し、さらに状態を変化させます。
19    echo "元のエンジンが生成した2番目の乱数: " . $originalEngine->generate() . "\n";
20
21    // Random\Engine\Xoshiro256StarStar インスタンスをシリアライズします。
22    // この際、PHP は内部的に __serialize() メソッドを呼び出し、
23    // オブジェクトの現在の状態を表現する配列を取得し、バイトストリームに変換します。
24    echo "\n--- 2. インスタンスのシリアライズ ---\n";
25    $serializedData = serialize($originalEngine);
26    // シリアライズされたデータは通常長い文字列になるため、一部のみ表示します。
27    echo "シリアライズされたデータ（一部抜粋）: " . substr($serializedData, 0, 100) . "...\n";
28
29    // シリアライズされたデータから新しいインスタンスをデシリアライズします。
30    // PHP はバイトストリームを解析し、元のオブジェクトの状態を復元します。
31    echo "\n--- 3. シリアライズされたデータからのデシリアライズ ---\n";
32    $deserializedEngine = unserialize($serializedData);
33
34    // デシリアライズされたオブジェクトが期待通りのクラスのインスタンスであることを確認します。
35    if ($deserializedEngine instanceof Random\Engine\Xoshiro256StarStar) {
36        echo "デシリアライズが成功し、Random\\Engine\\Xoshiro256StarStar のインスタンスが復元されました。\n";
37        // デシリアライズされたエンジンから乱数を生成します。
38        // 元のエンジンが中断した時点から乱数のシーケンスが引き継がれているはずです。
39        echo "デシリアライズされたエンジンが生成する3番目の乱数: " . $deserializedEngine->generate() . "\n";
40        echo "デシリアライズされたエンジンが生成する4番目の乱数: " . $deserializedEngine->generate() . "\n";
41        echo "↑ 元のエンジンの状態が正しく復元されたため、乱数のシーケンスが引き継がれていることが確認できます。\n";
42    } else {
43        echo "エラー: デシリアライズに失敗しました。期待される Random\\Engine\\Xoshiro256StarStar インスタンスが復元されませんでした。\n";
44    }
45}
46
47// サンプルコードを実行します。
48demonstrateSerialization();
49
50?>

Random\Engine\Xoshiro256StarStar::__serializeメソッドは、PHPのserialize()関数でこのクラスのオブジェクトを文字列に変換する際に、オブジェクトの内部状態を保存するための準備を行う特殊なメソッドです。

このメソッドは引数を受け取らず、現在のオブジェクトの状態を表現する連想配列を返します。PHPのserialize()関数は、このメソッドが返した配列をもとに、オブジェクトの情報をバイトストリームと呼ばれる文字列形式に効率的に変換します。

生成されたバイトストリームは、後でunserialize()関数によって処理されることで、オブジェクトが元の状態を保ったまま復元されます。特にRandom\Engine\Xoshiro256StarStarのような乱数エンジンでは、この機能によって乱数生成のシーケンス（続き）を正確に引き継ぐことができます。

サンプルコードでは、まず乱数エンジンを作成し、いくつかの乱数を生成して内部状態を変化させます。その後、serialize()関数でその状態をバイトストリームとして保存し、unserialize()関数で復元した新しいエンジンが、元のエンジンが中断した時点から乱数生成を再開する様子を確認しています。

このように、__serializeメソッドは、アプリケーションの実行中にオブジェクトの状態を一時的に保存したり、ネットワーク経由で他のシステムに転送したりするなど、オブジェクトの永続化や共有を可能にする重要なメカニズムを提供します。