PHPでローカル日時をUTCへ移行することは、サーバーのタイムゾーンを変更したり、一定の時間数を差し引いたりするだけではありません。データを変更する前に、各値が何を意味し、どのタイムゾーンで解釈されていたのか、特定の瞬間を示すのか、それとも暦上のルールなのかを確認する必要があります。これらが明らかでなければ、自動変換によってデータの形式は統一されても、誤った値のままになる可能性があります。
最も安全な方法は、段階的に進めることです。データを棚卸しし、データの種類ごとに方針を定め、新しいフィールドを追加して、バッチ単位で変換と検証を行い、移行が完了するまでは読み書きの互換性を保ちます。保存データが一貫した形で瞬間を表すようになっても、画面には従来どおりの時刻を表示できます。
現在の日付・時刻と依存関係を調査する
まず、日付と時刻のデータが存在する場所をすべて特定します。データベースのカラム、インポートファイル、キュー、API連携、PHPで生成される値などが対象です。型と運用上の規約も確認しましょう。DATETIMEカラムは通常、タイムゾーンを自ら保持せずに日付と時刻の各要素を保存します。TIMESTAMPでは、データベースエンジンやセッションに応じてタイムゾーン変換が行われる場合があります。型名だけから意味を推測してはいけません。
形式が混在していないかも調べます。たとえば、ローカル時刻を表すレコード、UTCを表すレコード、タイムゾーンが不明なソースからインポートされたレコードが混在しているかもしれません。サンプルを外部イベント、監査履歴、業務ルールと照合します。PHPの設定、データベース接続のタイムゾーン、デフォルトのタイムゾーンに依存するdate()やstrtotime()の呼び出しも確認してください。
同じ値でも、読み取るサーバーやプロセスによって表示が異なる場合はリスクの兆候です。季節によって変わる一定の時差も同様です。ローカル時刻とUTCが混在し、夏時間が影響している可能性があります。
瞬間、暦上の日付、繰り返しの時刻を区別する
瞬間とは、支払いが確定した時点のように、時間軸上の一意な一点です。UTCに正規化して保存でき、表示時にタイムゾーンを適用します。PHPではDateTimeImmutableとDateTimeZoneを使うと、元のタイムゾーンを明示して変換できます。
$local = new DateTimeImmutable($valor, new DateTimeZone('Europe/Madrid'));
$utc = $local->setTimezone(new DateTimeZone('UTC'));この例が有効なのは、入力された日付と時刻が検証済みで、一意な瞬間を表している場合に限られます。コンストラクターは、夏時間への切り替えで存在しないローカル時刻を黙って正規化することがあります。また、重複する時刻について、入力で指定されていない一方の時点を選ぶ場合があります。保存する前に時刻が存在することを検証し、重複時刻には明示的な方針を適用してください。たとえば、オフセットや元データの証拠に基づいて解決するか、レコードを要確認として扱います。瞬間を確実に特定できない場合は、暦上の値として保持するか、保留にします。PHPがオブジェクトを返したというだけで、変換が正しいと判断してはいけません。
一方、暦上の日付は、時刻やタイムゾーンを伴わない「4月14日」のような値です。誕生日や暦で定める期限に業務上の特定時刻が設定されていないなら、UTCの瞬間に変換してはいけません。別のタイムゾーンで表示したときに日付が変わるおそれがあります。
「会議は毎週月曜日の9時にマドリードで行う」のような繰り返しの時刻は、特定のタイムゾーンにおける暦上のルールです。タイムゾーンのオフセットは変わることがあるため、毎週同じUTCの瞬間を繰り返すこととは異なります。ローカル時刻、IANAタイムゾーン、繰り返しルールを保持し、その条件に基づいて次の瞬間を計算してください。
変換前に過去の意味を復元する
ローカル日時を変換するには、記録時に適用されていたタイムゾーンを把握する必要があります。現在のユーザーのタイムゾーンや、現在のサーバー設定を使うだけでは不十分です。アプリケーションが単一のタイムゾーンで運用されていた可能性もあれば、複数の拠点からデータが届いていた可能性もあります。過去の設定、レコードの取得元、関連アカウント、当時有効だったルールから根拠を探してください。
ローカル時刻だけでは、一意な瞬間を特定できない場合があります。時計が戻ると同じ時刻が2回発生し、時計が進むと存在しない時刻が生じます。日付のない時刻や、タイムゾーンなしでインポートされた日付など、不完全な値もあります。一般的な仮定を適用して黙って変換してはいけません。曖昧、存在しない、または取得元を検証できない値として分類し、担当部門と方針を定めてください。
ケースによっては、外部の根拠を使って重複時刻の一方を選ぶ、元の値を暦上のデータとして保持する、またはレコードを確認待ちにする必要があります。決定内容を記録し、Europe/MadridのようなIANAタイムゾーンを保存してください。「CET」のような略称だけでは、過去のルールを再構築するのに不十分な場合があります。
段階的で互換性のある移行を設計する
利用可能な唯一のカラムをすぐに上書きするのは避けてください。正規化した瞬間を保存する新しいフィールドを追加し、ドメイン上必要であれば、タイムゾーンまたは元の暦上の時刻を保存するフィールドも追加します。スキーマとコードの両方で各フィールドの意味を定義します。starts_at_utcのような名前は、アプリケーション全体で一貫して規約を守るなら役立ちます。
新旧のフィールドが併存する期間は、書き込みの唯一の正とするデータを決めてください。二重書き込みは移行を容易にする一方、一方だけが更新されてフィールド間に不整合が生じるリスクがあります。書き込み処理を一つの経路に集約し、必要に応じてトランザクションを使い、失敗を記録してください。読み取りでは優先順位を明示します。新しいフィールドに値があればそれを使い、まだ移行されていないレコードに限って旧フィールドにフォールバックします。
併存期間を限定し、進捗を測る方法を定めてください。旧フィールドの廃止を計画する前に、どのアプリケーション、レポート、エクスポート、API利用者がまだ旧フィールドを読んでいるか確認します。互換性を維持することは、二つの解釈をいつまでも残すことではありません。
バッチ単位で変換し、処理結果を検証する
安定した選択条件と、処理を再開できるマーカーを用いて、対象を適切なサイズのバッチに分けて処理します。変換は再実行可能でなければなりません。同じバッチを再実行しても、変換済みの日付が二重にずれてはいけません。検証段階では元の値を保持し、識別子、仮定したタイムゾーン、変換結果、例外を記録します。技術ログに不要な個人情報を含めないようにしてください。
バッチを更新する前にプレビューを計算し、代表的なケースを確認します。処理後は、件数、変換前後の値、NULLのレコード、エラーの分布を比較します。業務ドメイン上の性質も検証してください。たとえば、予約が業務上のタイムゾーンで想定される暦日に関連付けられたままであることを確認します。瞬間の場合は時差が正しくても、暦上の日付であるべき値の日付が変わったなら、誤りの可能性があります。
例外が合意した基準を超えた場合や、取得元が不明な値が見つかった場合は、処理を止めてください。ルールを修正するか、該当レコードを確認用に分離します。検証可能なケースと同じ変換に無理に当てはめてはいけません。
入力、読み取り、テストを適応させる
入力の境界では、ユーザーまたは業務に対応するタイムゾーンを使って日時を解釈し、想定する形式を検証します。そのタイムゾーンにおける存在性と曖昧さの確認を終えてから、瞬間を保存する際にUTCへ変換します。出力時には、その瞬間を表示に適したタイムゾーンへ変換します。APIでは、タイムゾーンを示す情報を含むタイムスタンプなど、曖昧さのない形式を合意し、各フィールドが瞬間と暦上の値のどちらを表すか文書化してください。
テストには、明示的なタイムゾーンと、夏時間の切り替え前後のケースを含めます。存在しない時刻と重複時刻、深夜、日付の境界、タイムゾーン間の変換を確認してください。往復テストも追加します。入力を解釈して瞬間を保存し、元のタイムゾーンで再表示したときに、期待する意味が保たれることを検証します。出力が正規化される場合、文字列が常に完全一致することを求めず、各要素と意味を検証してください。存在しない時刻が拒否されるか方針どおりに処理されること、重複時刻が定められたルールなしに解決されないこともテストします。
旧フィールド廃止のチェックリスト
- 各フィールドが瞬間、暦上の日付、繰り返しルールのいずれかに分類されている。
- 元のタイムゾーンが文書化され、曖昧なケースに明示的な方針がある。
- 新しい書き込み処理で唯一の正となるデータが守られ、互換読み取りには廃止期限が設定されている。
- バッチ変換を再開でき、例外の追跡記録が残る。
- テストで夏時間の変更、日付の境界、API、異なるタイムゾーンでの表示を網羅している。
- レポート、エクスポート、スケジュールタスク、連携処理が旧フィールドに依存しなくなっている。
移行が検証され、その解釈に依存する利用者がいなくなってから、旧フィールドを廃止してください。瞬間にはUTCを、暦上のルールにはIANAタイムゾーンを使い、各フィールドの意味を明確にすれば、画面に保存方式の内部詳細を見せることなく、曖昧さを減らせます。
