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

Copy
1<?php
2
3/**
4 * PHP 8のDateTime::__serializeメソッド (概念) と
5 * php.ini設定 serialize_precision の関連性を示すサンプルコード。
6 *
7 * 注意: PHPの組み込みDateTimeクラスは、ユーザーが直接オーバーライド可能な
8 *      __serializeマジックメソッドを持っていません。
9 *      このCustomDateTimeクラスは、DateTimeを継承し、ユーザーが__serializeを
10 *      実装した場合の挙動と、serialize_precisionの影響をデモンストレーションする
11 *      ためのものです。組み込みDateTimeのシリアライズは内部的なメカニズムで行われます。
12 */
13class CustomDateTime extends DateTime
14{
15    /**
16     * オブジェクトがserialize()関数によってシリアライズされる際に呼び出されます。
17     * このメソッドは、オブジェクトのプロパティを表現する連想配列を返します。
18     * PHP 8の組み込みDateTimeオブジェクトのシリアライズは、内部的に同様のデータ構造を
19     * 生成しますが、この例ではカスタムのプロパティも追加しています。
20     *
21     * @return array シリアライズされるオブジェクトの状態を表す配列。
22     */
23    public function __serialize(): array
24    {
25        // DateTimeオブジェクトの重要な状態（タイムスタンプとタイムゾーン）を
26        // 配列として返します。
27        // ここに、serialize_precisionの設定が影響を与える浮動小数点数を含めます。
28        return [
29            'timestamp' => $this->getTimestamp(),
30            'timezone' => $this->getTimezone()->getName(),
31            // serialize_precision の影響を示すための浮動小数点数。
32            // これはDateTimeオブジェクトの本来のプロパティではありませんが、
33            // __serializeが返す配列に含めることで、その影響を確認できます。
34            'example_float_data' => 123.4567890123456789,
35        ];
36    }
37
38    /**
39     * オブジェクトがunserialize()関数によってアンシリアライズされる際に呼び出されます。
40     * __serialize()が返した配列を受け取り、オブジェクトの状態を復元します。
41     *
42     * @param array $data __serialize()が返したデータ配列。
43     */
44    public function __unserialize(array $data): void
45    {
46        // タイムゾーンを設定し、その後にタイムスタンプを設定してDateTimeオブジェクトの状態を復元します。
47        $this->setTimezone(new DateTimeZone($data['timezone']));
48        $this->setTimestamp($data['timestamp']);
49        // 'example_float_data' は、このCustomDateTimeオブジェクトの本来のプロパティではないため、
50        // アンシリアライズされたオブジェクトに動的にプロパティとして追加します。
51        $this->example_float_data = $data['example_float_data'];
52    }
53}
54
55// -------- serialize_precision の設定とシリアライズの結果 --------
56
57// serialize_precision をデフォルト値（-1、すべての有効桁数）に設定
58// 浮動小数点数は可能な限り精度を保ってシリアライズされます。
59ini_set('serialize_precision', -1);
60echo "--- serialize_precision = -1 (デフォルト、全桁数保持) ---\n";
61
62$originalDateTime = new CustomDateTime('2023-10-27 15:30:00 Asia/Tokyo');
63echo "オリジナルの浮動小数点数: " . sprintf('%.17F', $originalDateTime->example_float_data) . "\n";
64
65$serializedStringDefault = serialize($originalDateTime);
66echo "シリアライズされた文字列:\n" . $serializedStringDefault . "\n\n";
67
68$unserializedDateTimeDefault = unserialize($serializedStringDefault);
69echo "アンシリアライズ後の浮動小数点数: " . sprintf('%.17F', $unserializedDateTimeDefault->example_float_data) . "\n\n";
70
71// serialize_precision を特定の桁数に設定（例: 5桁）
72// 浮動小数点数は指定された精度で丸められてシリアライズされます。
73ini_set('serialize_precision', 5);
74echo "--- serialize_precision = 5 (小数点以下5桁まで) ---\n";
75
76// 再度オブジェクトを作成し、シリアライズします。
77// 同じオブジェクトを再シリアライズしても、__serializeが再度呼ばれ、新しいini設定が適用されます。
78$originalDateTime2 = new CustomDateTime('2023-10-27 15:30:00 Asia/Tokyo');
79echo "オリジナルの浮動小数点数: " . sprintf('%.17F', $originalDateTime2->example_float_data) . "\n";
80
81$serializedStringPrecision = serialize($originalDateTime2);
82echo "シリアライズされた文字列:\n" . $serializedStringPrecision . "\n\n";
83
84$unserializedDateTimePrecision = unserialize($serializedStringPrecision);
85echo "アンシリアライズ後の浮動小数点数: " . sprintf('%.17F', $unserializedDateTimePrecision->example_float_data) . "\n";
86
87// 浮動小数点数の比較
88if (abs($unserializedDateTimeDefault->example_float_data - $unserializedDateTimePrecision->example_float_data) > PHP_FLOAT_EPSILON) {
89    echo "注意: serialize_precision の設定により、浮動小数点数の値が変化しました。\n";
90}

DateTime::__serializeは、PHP 8で導入されたマジックメソッドの一つで、DateTimeオブジェクトがserialize()関数によって文字列に変換される際に呼び出されます。このメソッドはオブジェクトの現在の状態を正確に表現する連想配列を返す役割を持ち、引数は取りません。戻り値はarray型で、オブジェクトの再構築に必要なすべての情報を含みます。

組み込みのDateTimeクラスは、ユーザーが直接このメソッドをオーバーライドすることはできませんが、内部的には同様のメカニズムを用いてシリアライズ処理を行っています。提供されたサンプルコードは、DateTimeを継承したクラスで__serializeを実装することで、その挙動とphp.ini設定のserialize_precisionがシリアライズに与える影響をデモンストレーションしています。

serialize_precisionは、シリアライズされるデータに含まれる浮動小数点数の精度を制御する設定です。この設定値を変更すると、__serializeメソッドが返す配列内の浮動小数点数が、指定された精度で丸められて文字列化されます。例えば、デフォルトの-1（全桁数保持）から特定の桁数に設定することで、データのサイズを減らしたり、意図しない精度の丸めが行われる可能性もあるため、浮動小数点数を扱う際にはこの設定に注意が必要です。これにより、オブジェクトのデータを効率的かつ正確に保存・転送できるようになります。

Copy
1<?php
2
3/**
4 * DateTimeオブジェクトをプロパティとして持つカスタムクラス。
5 * PHP 8で導入された__serializeと__unserializeマジックメソッドを実装し、
6 * オブジェクトがserialize()関数やunserialize()関数で処理される際の
7 * データのカスタマイズ方法を示します。
8 */
9class MyCustomData
10{
11    public string $name;
12    public DateTime $createdAt;
13    public int $id;
14
15    /**
16     * コンストラクタ。
17     */
18    public function __construct(string $name, DateTime $createdAt, int $id)
19    {
20        $this->name = $name;
21        $this->createdAt = $createdAt;
22        $this->id = $id;
23    }
24
25    /**
26     * オブジェクトがserialize()関数でシリアライズされる際に呼び出されます。
27     * シリアライズされるべきプロパティを連想配列で返します。
28     * DateTimeオブジェクトは直接ではなく、ISO 8601形式の文字列に変換して保存します。
29     * これにより、タイムゾーン情報なども保持しつつ、異なる環境間での互換性を高めます。
30     *
31     * @return array<string, mixed>
32     */
33    public function __serialize(): array
34    {
35        return [
36            'name' => $this->name,
37            'createdAt' => $this->createdAt->format(DateTime::ATOM),
38            'id' => $this->id,
39        ];
40    }
41
42    /**
43     * オブジェクトがunserialize()関数でデシリアライズされる際に呼び出されます。
44     * __serialize()によってシリアライズされたデータ配列を受け取り、
45     * オブジェクトのプロパティを再構築します。
46     *
47     * @param array<string, mixed> $data
48     */
49    public function __unserialize(array $data): void
50    {
51        $this->name = $data['name'];
52        // 文字列からDateTimeオブジェクトを再構築します。
53        // DateTime::ATOM形式はDateTimeコンストラクタで直接解析可能です。
54        $this->createdAt = new DateTime($data['createdAt']);
55        $this->id = $data['id'];
56    }
57
58    /**
59     * オブジェクトのデバッグ用文字列表現を提供します。
60     */
61    public function __toString(): string
62    {
63        return sprintf(
64            "ID: %d, Name: %s, Created At: %s (%s)",
65            $this->id,
66            $this->name,
67            $this->createdAt->format('Y-m-d H:i:s'),
68            $this->createdAt->getTimezone()->getName()
69        );
70    }
71}
72
73// 元のオブジェクトを作成（具体的な日時とタイムゾーンを指定）
74$originalData = new MyCustomData("Sample Item", new DateTime('2023-10-27 10:30:00', new DateTimeZone('Europe/Berlin')), 123);
75echo "元のオブジェクト: " . $originalData . "\n\n";
76
77// オブジェクトをシリアライズ。このとき__serialize()マジックメソッドが呼び出されます。
78$serializedString = serialize($originalData);
79echo "シリアライズされたデータ: " . $serializedString . "\n\n";
80
81// シリアライズされたデータをデシリアライズ。このとき__unserialize()マジックメソッドが呼び出されます。
82$unserializedData = unserialize($serializedString);
83echo "デシリアライズされたオブジェクト: " . $unserializedData . "\n\n";
84
85// 検証: 元のオブジェクトとデシリアライズされたオブジェクトの内容が一致するか確認
86echo "検証結果:\n";
87echo "  Nameの一致: " . ($originalData->name === $unserializedData->name ? "OK" : "NG") . "\n";
88echo "  CreatedAtの一致 (ISO形式): " . ($originalData->createdAt->format(DateTime::ATOM) === $unserializedData->createdAt->format(DateTime::ATOM) ? "OK" : "NG") . "\n";
89echo "  IDの一致: " . ($originalData->id === $unserializedData->id ? "OK" : "NG") . "\n";
90
91?>

PHP 8では、オブジェクトをファイルやデータベースなどに保存するために文字列に変換するserialize()関数と、その文字列を元のオブジェクトに復元するunserialize()関数が利用されます。クラス内に__serialize()メソッドを実装すると、オブジェクトがserialize()される際に、どのプロパティをどのように保存するかをカスタマイズできます。

__serialize()メソッドは引数を取らず、オブジェクト内で保存したいプロパティを連想配列として返します。サンプルコードでは、DateTimeオブジェクトを直接保存せず、DateTime::ATOM形式の文字列に変換しています。これにより、日付やタイムゾーン情報を正確に保持し、異なる環境間での互換性を高めます。

一方、unserialize()関数でオブジェクトが復元される際には、__unserialize()メソッドが呼び出されます。このメソッドは、__serialize()が返したデータ配列を引数として受け取り、それを使ってオブジェクトのプロパティを再構築します。例えば、文字列からDateTimeオブジェクトを正確に復元します。このように__serialize()と__unserialize()を組み合わせることで、複雑なオブジェクトのデータも安全かつ正確に保存・復元できるのです。

Copy
1<?php
2
3/**
4 * DateTimeオブジェクトの情報をJSON形式で出力するサンプルコードです。
5 *
6 * PHP 8のDateTime::__serializeマジックメソッドは、オブジェクトがserialize()関数で
7 * シリアライズされる際に、そのオブジェクトの状態を表す配列を返すように設計されています。
8 * このサンプルでは、__serializeが返すであろう配列の形式を参考に、
9 * DateTimeオブジェクトをjson_encode()でJSON形式に変換する方法を示します。
10 */
11class SerializableDateTime extends DateTime implements JsonSerializable
12{
13    /**
14     * オブジェクトがjson_encode()される際に自動的に呼び出されるメソッドです。
15     * DateTime::__serializeが返すようなオブジェクトの状態を表す配列を生成し、返します。
16     * これにより、DateTimeオブジェクトをカスタム形式でJSONに変換できます。
17     *
18     * @return array シリアライズされたDateTimeオブジェクトのデータ
19     */
20    public function jsonSerialize(): array
21    {
22        // __serializeマジックメソッドは、通常 'date', 'timezone_type', 'timezone'
23        // のキーを持つ配列を返します。これに倣って現在のオブジェクトから
24        // これらの情報を抽出し、配列として返します。
25        return [
26            'date' => $this->format('Y-m-d H:i:s.u'), // 日付と時刻（マイクロ秒まで含む）
27            'timezone_type' => $this->getTimezone()->getType(), // タイムゾーンのタイプ
28            'timezone' => $this->getTimezone()->getName(),     // タイムゾーン名
29        ];
30    }
31}
32
33// 現在の日時でSerializableDateTimeオブジェクトを作成します。
34// 例として、Asia/Tokyoタイムゾーンを設定します。
35$dateTimeObject = new SerializableDateTime('now', new DateTimeZone('Asia/Tokyo'));
36
37// SerializableDateTimeオブジェクトをJSON形式に変換します。
38// JsonSerializableインターフェースを実装しているため、jsonSerialize()メソッドが
39// 自動的に呼び出され、その戻り値がJSONにエンコードされます。
40// JSON_PRETTY_PRINTは、出力を見やすくするためのオプションです。
41$jsonOutput = json_encode($dateTimeObject, JSON_PRETTY_PRINT);
42
43// 生成されたJSON文字列を出力します。
44echo $jsonOutput;

このサンプルコードは、PHPのDateTimeオブジェクトをJSON形式で出力する方法を示しています。通常、DateTimeオブジェクトを直接json_encode()関数でJSONに変換することはできませんが、JsonSerializableインターフェースと、それを実装するjsonSerialize()メソッドを利用することで可能になります。

SerializableDateTimeクラスは、標準のDateTimeクラスを継承し、JsonSerializableインターフェースを実装しています。このインターフェースを実装すると、json_encode()関数でオブジェクトがJSONに変換される際に、オブジェクトの状態をJSONに適した形式で表現するためのjsonSerialize()メソッドが自動的に呼び出されます。

jsonSerialize()メソッドは、引数を必要とせず、オブジェクトの現在の状態を表す配列を戻り値として返します。このサンプルでは、PHP 8で導入されたDateTime::__serializeマジックメソッドが内部的に使用する形式を参考に、日付、時刻、タイムゾーンのタイプ、タイムゾーン名といった情報を抽出し、配列としてまとめています。

最終的に、json_encode()関数は、このjsonSerialize()メソッドが返した配列を受け取り、その内容を基に整形されたJSON文字列を生成します。これにより、DateTimeオブジェクトの情報を柔軟にJSON形式で扱うことが可能となります。

Copy
1<?php
2
3/**
4 * DateTime::__serialize メソッドの動作を示すサンプルコード。
5 *
6 * PHP 8.1 以降では、DateTime オブジェクトは __serialize メソッドを実装しており、
7 * serialize() 関数でシリアライズ可能です。このメソッドは、オブジェクトがシリアライズされる際に
8 * 内部的に呼び出され、オブジェクトの状態を配列として返します。
9 * このサンプルでは、DateTime オブジェクトのシリアライズとアンシリアライズを行い、
10 * データが正しく復元されることを確認します。
11 *
12 * 注意: PHP 8.0 では DateTime::__serialize は存在しません。このコードは PHP 8.1 以降で動作します。
13 */
14
15// 現在の日時を持つ DateTime オブジェクトを作成します。
16$originalDateTime = new DateTime('2023-10-27 10:30:00', new DateTimeZone('Asia/Tokyo'));
17echo "元の DateTime オブジェクト: " . $originalDateTime->format('Y-m-d H:i:s P') . PHP_EOL;
18
19// DateTime オブジェクトをシリアライズします。
20// この操作により、内部的に DateTime::__serialize メソッドが呼び出されます。
21$serializedString = serialize($originalDateTime);
22echo "シリアライズされた文字列: " . $serializedString . PHP_EOL;
23
24// シリアライズされた文字列をアンシリアライズして、DateTime オブジェクトを復元します。
25// この操作により、内部的に DateTime::__unserialize メソッドが呼び出されます。
26$unserializedDateTime = unserialize($serializedString);
27
28// 復元されたオブジェクトの内容を確認し、元のオブジェクトと比較します。
29if ($unserializedDateTime instanceof DateTime) {
30    echo "アンシリアライズされた DateTime オブジェクト: " . $unserializedDateTime->format('Y-m-d H:i:s P') . PHP_EOL;
31
32    // オブジェクトの比較には == 演算子を使用します。
33    if ($originalDateTime == $unserializedDateTime) {
34        echo "--> シリアライズとアンシリアライズが成功し、オブジェクトの内容が一致します。" . PHP_EOL;
35    } else {
36        echo "--> エラー: シリアライズとアンシリアライズ後にオブジェクトの内容が一致しません。" . PHP_EOL;
37    }
38} else {
39    echo "--> エラー: アンシリアライズに失敗しました。" . PHP_EOL;
40}

PHPのDateTimeクラスに用意されている__serializeメソッドは、DateTimeオブジェクトをデータとして保存したり、別の場所に転送したりする際に役立つ特別な機能です。このメソッドはPHP 8.1以降で導入されました。

具体的には、serialize()関数を使ってDateTimeオブジェクトを文字列に変換する際、内部的にこの__serializeメソッドが呼び出されます。引数はなく、DateTimeオブジェクトの現在の日時やタイムゾーンといった状態を正確に表す配列を戻り値として返します。この配列データが、最終的にserialize()関数によってバイト列の文字列に変換されます。

サンプルコードでは、まず特定の日時を持つDateTimeオブジェクトを作成します。次に、serialize()関数でこのオブジェクトをシリアライズ文字列に変換し、その文字列を出力します。その後、unserialize()関数を使ってシリアライズ文字列を元のDateTimeオブジェクトに復元します。この復元処理では、内部的にDateTime::__unserializeメソッドが使われます。最終的に、復元されたオブジェクトが元のオブジェクトと完全に一致することを確認することで、__serializeメソッドがオブジェクトの状態を正確に保存し、復元できることを示しています。このように、__serializeはオブジェクトの永続化やデータ交換を安全に行うために重要な役割を果たします。