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

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setTimezone メソッドを使用して、
5 * 日時オブジェクトのタイムゾーンをUTCに変更するサンプルコードです。
6 *
7 * DateTimeImmutable オブジェクトは変更不可 (immutable) であるため、
8 * setTimezone メソッドは新しい DateTimeImmutable オブジェクトを返します。
9 */
10function setTimezoneToUtcExample(): void
11{
12    // 1. まず、任意のタイムゾーンを持つDateTimeImmutableオブジェクトを作成します。
13    //    ここでは、東京のタイムゾーンで現在日時を取得します。
14    $tokyoTimezone = new DateTimeZone('Asia/Tokyo');
15    $originalDateTime = new DateTimeImmutable('now', $tokyoTimezone);
16
17    echo "元の日時 (東京): " . $originalDateTime->format('Y-m-d H:i:s P') . "\n";
18    echo "元のタイムゾーン: " . $originalDateTime->getTimezone()->getName() . "\n\n";
19
20    // 2. UTCタイムゾーンのDateTimeZoneオブジェクトを作成します。
21    $utcTimezone = new DateTimeZone('UTC');
22
23    // 3. setTimezone メソッドを呼び出し、タイムゾーンをUTCに設定した新しいオブジェクトを取得します。
24    //    元の $originalDateTime オブジェクトは変更されません。
25    $utcDateTime = $originalDateTime->setTimezone($utcTimezone);
26
27    echo "UTCに変更後の日時: " . $utcDateTime->format('Y-m-d H:i:s P') . "\n";
28    echo "UTCに変更後のタイムゾーン: " . $utcDateTime->getTimezone()->getName() . "\n";
29
30    // 注意: setTimezone は時刻の「瞬間」を変更するのではなく、
31    //       その瞬間をどのタイムゾーンのオフセットで表示するかを変更します。
32    //       例: 東京の午前10時は、UTCの午前1時と同じ瞬間です。
33}
34
35// 関数を実行して動作を確認します。
36setTimezoneToUtcExample();
37
38?>

PHPのDateTimeImmutableクラスに属するsetTimezoneメソッドは、日時オブジェクトのタイムゾーンを変更するために利用されます。このメソッドは、引数としてDateTimeZoneオブジェクトを受け取ります。この引数は、日時オブジェクトに設定したい新しいタイムゾーンを指定するものです。

DateTimeImmutableオブジェクトはその名の通り「不変（immutable）」という特性を持っており、一度作成されたオブジェクトの状態は変更されません。そのため、setTimezoneメソッドを呼び出しても、元のDateTimeImmutableオブジェクト自体が変更されることはありません。その代わり、指定された新しいタイムゾーンが適用された、新しいDateTimeImmutableオブジェクトが生成されて戻り値として返されます。

例えば、東京のタイムゾーンで設定された日時オブジェクトがあり、それを協定世界時（UTC）に変換したい場合を考えてみましょう。まず、new DateTimeZone('UTC')のようにUTCのDateTimeZoneオブジェクトを作成します。次に、元の東京の日時オブジェクトに対してsetTimezoneメソッドを呼び出し、このUTCのDateTimeZoneオブジェクトを引数に渡します。これにより、元のオブジェクトはそのままに、時刻の「瞬間」は変わらず、表示上のタイムゾーンがUTCに調整された新しい日時オブジェクトが手に入ります。これは、異なるタイムゾーン間での時刻表示を調整し、正確な日時情報を扱う上で非常に重要な機能です。

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setTimezone メソッドの使用例をデモンストレーションします。
5 * このメソッドは、DateTimeImmutable オブジェクトのタイムゾーンを設定し、
6 * 新しい DateTimeImmutable オブジェクトを返します（元のオブジェクトは変更しません）。
7 */
8function demonstrateDateTimeImmutableSetTimezone(): void
9{
10    // 1. 現在の時刻で DateTimeImmutable オブジェクトを作成します。
11    //    デフォルトのタイムゾーン（通常はサーバー設定）で初期化されます。
12    $currentTime = new DateTimeImmutable();
13    echo "元の時刻 (デフォルトのタイムゾーン): " . $currentTime->format('Y-m-d H:i:s P') . "\n";
14    echo "元のタイムゾーン名: " . $currentTime->getTimezone()->getName() . "\n\n";
15
16    // 2. タイムゾーン 'Asia/Tokyo' を表す DateTimeZone オブジェクトを作成します。
17    $tokyoTimezone = new DateTimeZone('Asia/Tokyo');
18
19    // 3. setTimezone メソッドを使用して、タイムゾーンを 'Asia/Tokyo' に変更します。
20    //    このメソッドは新しい DateTimeImmutable オブジェクトを返します。
21    $timeInTokyo = $currentTime->setTimezone($tokyoTimezone);
22
23    echo "東京タイムゾーンに設定後の時刻: " . $timeInTokyo->format('Y-m-d H:i:s P') . "\n";
24    echo "東京タイムゾーン名: " . $timeInTokyo->getTimezone()->getName() . "\n\n";
25
26    // 4. 別のタイムゾーン 'America/New_York' に変更してみます。
27    $newYorkTimezone = new DateTimeZone('America/New_York');
28    $timeInNewYork = $currentTime->setTimezone($newYorkTimezone);
29
30    echo "ニューヨークタイムゾーンに設定後の時刻: " . $timeInNewYork->format('Y-m-d H:i:s P') . "\n";
31    echo "ニューヨークタイムゾーン名: " . $timeInNewYork->getTimezone()->getName() . "\n\n";
32
33    // 5. 元の $currentTime オブジェクトは変更されていないことを確認します。
34    //    DateTimeImmutable オブジェクトは不変（immutable）であるため、
35    //    元のオブジェクトは setTimezone を呼び出しても影響を受けません。
36    echo "元のオブジェクトは変更されていません: " . $currentTime->format('Y-m-d H:i:s P') . "\n";
37    echo "元のオブジェクトのタイムゾーン: " . $currentTime->getTimezone()->getName() . "\n";
38}
39
40// 関数を実行して、DateTimeImmutable::setTimezone の動作を確認します。
41demonstrateDateTimeImmutableSetTimezone();

PHPのDateTimeImmutable::setTimezoneメソッドは、日付と時刻を扱うDateTimeImmutableオブジェクトのタイムゾーンを変更するために使用されます。このメソッドは、引数として変更したいタイムゾーンを表すDateTimeZoneオブジェクトを受け取ります。例えば、new DateTimeZone('Asia/Tokyo')のように、目的のタイムゾーン名でDateTimeZoneオブジェクトを作成し、それをsetTimezoneメソッドに渡します。

DateTimeImmutableクラスの重要な特徴として「不変（immutable）」であることが挙げられます。これは、setTimezoneメソッドを呼び出しても、呼び出し元のDateTimeImmutableオブジェクト自身は変更されないという意味です。その代わりに、新しいタイムゾーンが適用された新しいDateTimeImmutableオブジェクトが戻り値として返されます。

サンプルコードでは、まず現在の時刻でDateTimeImmutableオブジェクトを作成し、そのデフォルトのタイムゾーンと時刻を表示しています。次に、new DateTimeZone('Asia/Tokyo')で東京のタイムゾーンオブジェクトを作成し、setTimezoneメソッドを使って東京の時刻を表す新しいオブジェクトを生成します。同様にニューヨークのタイムゾーンへも変換できます。これらの操作を行っても、最初に作成した元の時刻オブジェクトは一切変更されず、初期状態を保ちます。format('Y-m-d H:i:s P')のようにPを指定することで、タイムゾーンによるUTCからの時差も表示され、正しく変更されたことを確認できます。