【PHP8.x】getOffsetメソッドの使い方

Copy
1<?php
2
3// DateTimeImmutable::getOffset() メソッドの使用例
4
5/**
6 * 指定されたDateTimeImmutableオブジェクトのUTCからのオフセット（秒単位）を取得し、
7 * その詳細情報を表示する関数。
8 *
9 * @param DateTimeImmutable $dateTimeImmutable オフセットを取得するDateTimeImmutableオブジェクト
10 * @return void
11 */
12function displayOffsetInfo(DateTimeImmutable $dateTimeImmutable): void
13{
14    // DateTimeImmutable::getOffset() メソッドを呼び出し、UTCからのオフセットを秒単位で取得します。
15    // 戻り値は整数 (int) です。
16    $offsetSeconds = $dateTimeImmutable->getOffset();
17
18    // 取得した秒単位のオフセットを、時間と分に変換して分かりやすく表示します。
19    $offsetHours = floor(abs($offsetSeconds) / 3600);
20    $offsetMinutes = floor((abs($offsetSeconds) % 3600) / 60);
21    $sign = ($offsetSeconds >= 0) ? '+' : '-';
22    $offsetFormatted = sprintf("%s%02d:%02d", $sign, $offsetHours, $offsetMinutes);
23
24    echo "--- タイムゾーン: " . $dateTimeImmutable->getTimezone()->getName() . " ---" . PHP_EOL;
25    // Pフォーマットは、UTCからのオフセットを `+HH:MM` または `-HH:MM` の形式で表示します。
26    echo "  日時 (ローカル): " . $dateTimeImmutable->format('Y-m-d H:i:s P') . PHP_EOL;
27    echo "  UTCからのオフセット (秒): " . $offsetSeconds . PHP_EOL;
28    echo "  UTCからのオフセット (HH:MM): " . $offsetFormatted . PHP_EOL;
29    echo PHP_EOL;
30}
31
32// 1. デフォルトのタイムゾーンでDateTimeImmutableオブジェクトを作成し、オフセットを表示
33//    (この場合、PHP設定のデフォルトタイムゾーンが使用されます)
34echo "=== デフォルトタイムゾーンの例 ===" . PHP_EOL;
35$dateTimeDefault = new DateTimeImmutable();
36displayOffsetInfo($dateTimeDefault);
37
38// 2. 特定のタイムゾーン (例: Asia/Tokyo) でDateTimeImmutableオブジェクトを作成し、オフセットを表示
39echo "=== 特定のタイムゾーン (Asia/Tokyo) の例 ===" . PHP_EOL;
40$timeZoneTokyo = new DateTimeZone('Asia/Tokyo');
41$dateTimeTokyo = new DateTimeImmutable('now', $timeZoneTokyo);
42displayOffsetInfo($dateTimeTokyo);
43
44// 3. 別の特定のタイムゾーン (例: America/New_York) でDateTimeImmutableオブジェクトを作成し、オフセットを表示
45echo "=== 別のタイムゾーン (America/New_York) の例 ===" . PHP_EOL;
46$timeZoneNewYork = new DateTimeZone('America/New_York');
47$dateTimeNewYork = new DateTimeImmutable('now', $timeZoneNewYork);
48displayOffsetInfo($dateTimeNewYork);
49
50// 4. サマータイムがあるタイムゾーンでのオフセットの変化の例
51//    (DateTimeImmutable::getOffset()は、指定された日付/時刻における正確なオフセットを返します)
52echo "=== サマータイムによるオフセット変化の例 (America/Los_Angeles) ===" . PHP_EOL;
53
54// サマータイム実施中の日付 (例: 2023年7月1日) でオフセットを取得
55$dateTimeLA_Summer = new DateTimeImmutable('2023-07-01 12:00:00', new DateTimeZone('America/Los_Angeles'));
56displayOffsetInfo($dateTimeLA_Summer);
57
58// サマータイム非実施中の日付 (例: 2023年1月1日) でオフセットを取得
59$dateTimeLA_Winter = new DateTimeImmutable('2023-01-01 12:00:00', new DateTimeZone('America/Los_Angeles'));
60displayOffsetInfo($dateTimeLA_Winter);

PHP 8のDateTimeImmutableクラスに属するgetOffset()メソッドは、特定のDateTimeImmutableオブジェクトが表す日時が、UTC（協定世界時）からどれだけずれているか（オフセット）を秒単位の整数値で取得します。このメソッドは引数を必要としません。戻り値は常にint型で、UTCよりも時間が進んでいる場合は正の数、遅れている場合は負の数を返します。

サンプルコードでは、DateTimeImmutable::getOffset()メソッドを使って、さまざまなタイムゾーンやサマータイムの有無によるオフセットの違いを確認できます。例えば、Asia/TokyoのタイムゾーンではUTCから9時間進んでいるため、+32400秒（9時間 × 3600秒）が返されます。一方、America/New_YorkではUTCより5時間遅れているため、-18000秒が返されます。また、サマータイムを導入している地域では、日付によってオフセットが変わることもgetOffset()は正確に反映します。このメソッドは、プログラムで異なるタイムゾーンの日時を扱う際に、その時刻の正確なUTCからの時差を知りたい場合に役立ちます。