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

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setTime メソッドの基本的な使用例。
5 * 現在の日付を維持しつつ、特定の時刻（時、分、秒、マイクロ秒）を設定した
6 * 新しいDateTimeImmutableオブジェクトを生成します。
7 * これは、特定の日付における「開始時刻」「終了時刻」「期限時刻」などを定義する際に役立ちます。
8 *
9 * @param int $hour        時 (0-23)
10 * @param int $minute      分 (0-59)
11 * @param int $second      秒 (0-59, デフォルトは 0)
12 * @param int $microsecond マイクロ秒 (0-999999, デフォルトは 0)
13 * @return DateTimeImmutable 指定された時刻が設定された新しいDateTimeImmutableオブジェクト
14 */
15function createDateTimeWithSpecificTime(
16    int $hour,
17    int $minute,
18    int $second = 0,
19    int $microsecond = 0
20): DateTimeImmutable {
21    // 現在の日時でDateTimeImmutableオブジェクトを生成します。
22    // DateTimeImmutableは「不変（immutable）」オブジェクトです。
23    // これは、メソッドを呼び出しても元のオブジェクトの状態は変更されず、
24    // 常に新しいオブジェクトが返されることを意味します。
25    $originalDateTime = new DateTimeImmutable();
26    echo "元の日時: " . $originalDateTime->format('Y-m-d H:i:s.u') . "\n";
27
28    // setTimeメソッドを使用して、元のオブジェクトの日付部分はそのままに、
29    // 時刻部分だけを新しい値に設定します。
30    // 例えば、今日の業務の「終了時刻」や、ある処理の「タイムアウト時刻」を
31    // 特定の時刻として設定する際にこのメソッドを利用できます。
32    $newDateTime = $originalDateTime->setTime($hour, $minute, $second, $microsecond);
33
34    echo "新しい時刻が設定された日時: " . $newDateTime->format('Y-m-d H:i:s.u') . "\n\n";
35
36    return $newDateTime;
37}
38
39// --- 使用例 ---
40
41// 例1: 今日の午後5時30分00秒を「今日の締め切り時刻」として設定
42echo "--- 例1: 午後5時30分00秒の設定 ---\n";
43createDateTimeWithSpecificTime(17, 30, 0);
44
45// 例2: 今日の午前9時00分123456マイクロ秒を「今日の開始時刻」として設定
46echo "--- 例2: 午前9時00分123456マイクロ秒の設定 ---\n";
47createDateTimeWithSpecificTime(9, 0, 0, 123456);

PHPのDateTimeImmutable::setTimeメソッドは、既存のDateTimeImmutableオブジェクトの日付情報を保持したまま、時刻部分を新しく設定するために利用されます。このメソッドは、指定された時、分、秒、マイクロ秒をオブジェクトの新しい時刻として設定します。

引数としては、$hourで時（0-23）、$minuteで分（0-59）を指定します。オプションで$second（0-59）と$microsecond（0-999999）も指定でき、これらを省略した場合はそれぞれ0がデフォルト値となります。

DateTimeImmutableクラスは「不変（immutable）」であるため、setTimeメソッドを呼び出しても元のオブジェクト自体は変更されません。その代わりに、設定された新しい時刻を持つ新たなDateTimeImmutableオブジェクトが戻り値として返されます。

この機能は、特定の日付における開始時刻や終了時刻、あるいは何らかの処理のタイムアウト時刻など、日付はそのままに時刻だけを柔軟に設定したい場合に非常に役立ちます。

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setTime メソッドの使用例を示します。
5 * 特定のタイムゾーンを持つ日時オブジェクトの時刻部分を設定する方法を説明します。
6 */
7function demonstrateSetTimeWithTimezone(): void
8{
9    // タイムゾーンを指定してDateTimeImmutableオブジェクトを作成します。
10    // まずは 'Asia/Tokyo' タイムゾーンで作成。
11    $tokyoTimezone = new DateTimeZone('Asia/Tokyo');
12    $dateTimeTokyo = new DateTimeImmutable('2023-10-26 10:30:00', $tokyoTimezone);
13
14    echo "--- タイムゾーン: Asia/Tokyo ---\n";
15    echo "元の日時: " . $dateTimeTokyo->format('Y-m-d H:i:s P') . "\n";
16
17    // setTimeメソッドを使用して、時刻部分のみを変更します。
18    // 日付とタイムゾーンは元のオブジェクトのものが維持されます。
19    // 時刻を 15時45分30秒 に設定。マイクロ秒はデフォルト値の 0 が使用されます。
20    $newDateTimeTokyo = $dateTimeTokyo->setTime(15, 45, 30);
21    echo "setTime後の日時: " . $newDateTimeTokyo->format('Y-m-d H:i:s P') . "\n\n";
22
23    // 次に 'America/New_York' タイムゾーンで同じ操作を行います。
24    $newYorkTimezone = new DateTimeZone('America/New_York');
25    $dateTimeNewYork = new DateTimeImmutable('2023-10-26 10:30:00', $newYorkTimezone);
26
27    echo "--- タイムゾーン: America/New_York ---\n";
28    echo "元の日時: " . $dateTimeNewYork->format('Y-m-d H:i:s P') . "\n";
29
30    // こちらのオブジェクトも setTime で時刻を変更します。
31    // タイムゾーンが異なっていても、ローカル時刻として設定されます。
32    // マイクロ秒も指定する例: 15時45分30秒123456マイクロ秒に設定。
33    $newDateTimeNewYork = $dateTimeNewYork->setTime(15, 45, 30, 123456);
34    echo "setTime後の日時: " . $newDateTimeNewYork->format('Y-m-d H:i:s.u P') . "\n";
35}
36
37// 関数を実行してサンプルコードの動作を確認します。
38demonstrateSetTimeWithTimezone();

PHP 8のDateTimeImmutable::setTimeメソッドは、DateTimeImmutableオブジェクトの日付とタイムゾーンを保持しつつ、時刻部分のみを変更するためのものです。このメソッドは、引数として渡された時、分、秒、マイクロ秒に基づいて、新しい時刻を設定します。

引数には、$hourに時（0-23）、$minuteに分（0-59）、$secondに秒（0-59）、$microsecondにマイクロ秒（0-999999）を整数で指定します。$secondと$microsecondはオプションで、省略された場合は0が使用されます。

DateTimeImmutableクラスの性質上、このメソッドは元のオブジェクトを変更せず、時刻が変更された新しいDateTimeImmutableオブジェクトを戻り値として返します。これにより、元のオブジェクトを保ちながら、異なる時刻を持つ新しいオブジェクトを柔軟に作成できます。

サンプルコードでは、Asia/TokyoとAmerica/New_Yorkという異なるタイムゾーンで作成された日時オブジェクトに対してsetTimeを適用する例を示しています。どちらの場合も、指定した時刻がそのタイムゾーンにおけるローカル時刻として正確に設定され、日付とタイムゾーンは元のオブジェクトのものが維持されます。マイクロ秒も指定できることが確認できます。