【PHP8.x】timezone_offset_get関数の使い方

<?php

/**
 * 現在のタイムゾーンのオフセット（秒単位）を取得するサンプルコード
 */

// タイムゾーンを設定
date_default_timezone_set('Asia/Tokyo');

// 現在のタイムゾーンオブジェクトを作成
$timezone = new DateTimeZone(date_default_timezone_get());

// 現在時刻の DateTimeImmutable オブジェクトを作成
$datetime = new DateTimeImmutable();

// タイムゾーンのオフセットを取得
$offset = timezone_offset_get($timezone, $datetime);

// 結果を出力
echo '現在のタイムゾーンオフセット (秒): ' . $offset . PHP_EOL;

?>

このサンプルコードは、PHPで現在のタイムゾーンのオフセット（UTCからのずれ）を秒単位で取得する方法を示しています。システムエンジニアを目指す方が、タイムゾーンを扱う際の基礎として役立つでしょう。

まず、date_default_timezone_set()関数を使用して、スクリプトで使用するデフォルトのタイムゾーンを 'Asia/Tokyo' に設定します。これにより、以降のDateTime関連の処理が特定のタイムゾーンに基づいて行われるようになります。

次に、DateTimeZoneクラスのインスタンスを作成し、date_default_timezone_get()関数で取得したタイムゾーン名を渡します。このDateTimeZoneオブジェクトが、タイムゾーン情報を保持します。

DateTimeImmutableクラスは、変更不可能な日時オブジェクトを作成するために使用されます。ここでは、現在時刻を表すDateTimeImmutableオブジェクトを作成しています。

そして、timezone_offset_get()関数を使用して、指定されたDateTimeZoneオブジェクトとDateTimeInterfaceオブジェクト（ここではDateTimeImmutableオブジェクト）に基づいて、タイムゾーンのオフセットを秒単位で取得します。この関数は、第一引数にDateTimeZoneオブジェクト、第二引数にDateTimeInterfaceを実装した日時オブジェクトを渡します。戻り値として、UTCからのずれを秒単位で表す数値が返されます。

最後に、取得したオフセット値を echo で出力します。これにより、現在のタイムゾーンがUTCからどれだけずれているかを確認できます。このサンプルコードを実行することで、PHPにおけるタイムゾーンの扱い方と、オフセットの取得方法を理解することができます。

<?php

declare(strict_types=1);

/**
 * 指定したタイムゾーンと日時のUTCからのオフセット（時差）を取得して表示します。
 *
 * `timezone_offset_get` は、DateTimeZoneオブジェクトとDateTimeInterfaceオブジェクトを
 * 引数に取り、指定された日時におけるUTCからのオフセットを秒単位の整数で返します。
 * 夏時間（サマータイム）も考慮されます。
 *
 * @param string $timezoneIdentifier タイムゾーン識別子 (例: 'Asia/Tokyo', 'America/New_York')
 * @param string $dateTimeString     日時を表す文字列 (例: '2024-08-01 10:00:00')
 * @return void
 */
function displayTimezoneOffsetExample(string $timezoneIdentifier, string $dateTimeString): void
{
    try {
        // 1. タイムゾーンを表す DateTimeZone オブジェクトを生成します。
        $timezone = new DateTimeZone($timezoneIdentifier);

        // 2. 日時を表す DateTime オブジェクトを生成します。
        //    この日時が、どの時点でのオフセットを取得するかの基準になります。
        $datetime = new DateTime($dateTimeString, $timezone);

        // 3. timezone_offset_get() を呼び出し、UTCからのオフセットを秒単位で取得します。
        $offsetInSeconds = timezone_offset_get($timezone, $datetime);

        // 4. 人間が読みやすいように、時差を「+HH:MM」形式に変換します。
        $hours = floor(abs($offsetInSeconds) / 3600);
        $minutes = floor((abs($offsetInSeconds) % 3600) / 60);
        $sign = ($offsetInSeconds >= 0) ? '+' : '-';
        $offsetFormatted = sprintf('%s%02d:%02d', $sign, $hours, $minutes);

        // 結果を出力します。
        printf(
            "タイムゾーン '%s' の日時 '%s' 時点でのUTCオフセット:\n",
            $timezoneIdentifier,
            $datetime->format('Y-m-d H:i:s')
        );
        printf("  - %d 秒\n", $offsetInSeconds);
        printf("  - %s\n\n", $offsetFormatted);

    } catch (Exception $e) {
        // タイムゾーン識別子が不正な場合などのエラーを処理します。
        echo "エラー: " . $e->getMessage() . "\n";
    }
}

// --- 実行例 ---

// 日本時間 (JST) は常にUTC+9時間です。
displayTimezoneOffsetExample('Asia/Tokyo', '2024-11-01 12:00:00');

// ニューヨークの冬時間 (EST) は UTC-5時間です。
displayTimezoneOffsetExample('America/New_York', '2024-11-01 12:00:00');

// ニューヨークの夏時間 (EDT) は UTC-4時間です。
// このように、同じタイムゾーンでも日時によってオフセットが変わることが分かります。
displayTimezoneOffsetExample('America/New_York', '2024-08-01 12:00:00');

?>

PHPのtimezone_offset_get関数は、指定されたタイムゾーンと特定の日時において、UTC（協定世界時）からの時差（オフセット）を秒単位で取得するために使用されます。この関数は、第一引数にタイムゾーンを表すDateTimeZoneオブジェクトを、第二引数にオフセット計算の基準となる日時を表すDateTimeInterfaceオブジェクトを取ります。特に、夏時間（サマータイム）が適用される地域では、同じタイムゾーンであっても日時によってUTCからのオフセットが変化するため、DateTimeInterfaceオブジェクトで正確な日時を指定することが重要です。この関数は、UTCからのオフセットを整数値（秒単位）で返します。

提供されたサンプルコードでは、displayTimezoneOffsetExample関数内で、まず指定されたタイムゾーン識別子と日時文字列からDateTimeZoneおよびDateTimeオブジェクトをそれぞれ生成しています。その後、timezone_offset_get関数を呼び出して秒単位のオフセットを取得し、その結果を人間が読みやすい「+HH:MM」形式に変換して表示しています。複数の実行例を通して、同じタイムゾーンでも日時（冬時間や夏時間）によってオフセットが異なることが分かりやすく示されており、システムが正確な時刻情報を扱う上で非常に役立つ機能です。