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

<?php

// 現在の日付と時刻を持つDateTimeオブジェクトを作成します。
// 例: '2023-10-27 15:30:45.123456' のような日時で初期化されます。
$dateTime = new DateTime();

// 時刻設定前のDateTimeオブジェクトを表示します。
echo "元のDateTimeオブジェクト: " . $dateTime->format('Y-m-d H:i:s.u') . PHP_EOL;

// date_time_set() メソッドを使って、DateTimeオブジェクトの時刻を00:00:00.000000に設定します。
// 引数は (時, 分, 秒, マイクロ秒) の順です。
// このメソッドは、対象のDateTimeオブジェクト自身を変更し、そのオブジェクトを返します。
$dateTime->date_time_set(0, 0, 0, 0);

// 時刻設定後のDateTimeオブジェクトを表示します。
// 日付は変更されず、時刻のみが00:00:00に設定されていることを確認できます。
echo "時刻を00:00:00に設定後のDateTimeオブジェクト: " . $dateTime->format('Y-m-d H:i:s.u') . PHP_EOL;

// 特定の日付で時刻を00:00:00に設定する別の例
$specificDateTime = new DateTime('2024-01-15 10:20:30.987654');
echo "元の特定日付DateTimeオブジェクト: " . $specificDateTime->format('Y-m-d H:i:s.u') . PHP_EOL;

$specificDateTime->date_time_set(0, 0, 0, 0);
echo "時刻を00:00:00に設定後の特定日付DateTimeオブジェクト: " . $specificDateTime->format('Y-m-d H:i:s.u') . PHP_EOL;

?>

PHPのDateTimeオブジェクトが提供するdate_time_setメソッドは、既存のDateTimeオブジェクトの時刻部分（時、分、秒、マイクロ秒）を任意の値に設定するために使用されます。

サンプルコードでは、まずnew DateTime()を使って現在の日付と時刻を持つDateTimeオブジェクトを作成し、その初期値として表示しています。次に、$dateTime->date_time_set(0, 0, 0, 0)を呼び出し、引数に『時：0、分：0、秒：0、マイクロ秒：0』を指定することで、このDateTimeオブジェクトの時刻を一日の始まりである『00:00:00.000000』に設定しています。

このメソッドは、最初の引数で指定されたDateTimeオブジェクト自身を変更し、変更後のそのオブジェクトを戻り値として返します。日付部分は変更されず、時刻だけが指定された値に更新されるのが特徴です。コードを実行すると、元のDateTimeオブジェクトの日付はそのままに、時刻だけが00:00:00に更新されていることが確認できます。2つ目の例でも、任意の日付を持つDateTimeオブジェクトに対し、同様にdate_time_setメソッドで時刻を00:00:00に設定し、その結果を示しています。

<?php

/**
 * PHPの date_time_set 関数を使用して DateTime オブジェクトの時刻を設定し、
 * タイムゾーンの扱われ方を示すサンプルコードです。
 *
 * この関数は、既存の DateTime オブジェクトの日付部分を維持したまま、
 * 時刻 (時、分、秒、マイクロ秒) を変更します。
 * また、タイムゾーンが設定された DateTime オブジェクトに時刻を設定し、
 * その後タイムゾーンを変更した場合の表示の変化も示します。
 */
function demonstrateDateTimeSetWithTimezone(): void
{
    // 1. タイムゾーンを定義します。ここでは「America/New_York」を使用します。
    $newYorkTimezone = new DateTimeZone('America/New_York');

    // 2. 現在の日時を、指定したタイムゾーン付きで DateTime オブジェクトとして初期化します。
    $dateTime = new DateTime('now', $newYorkTimezone);

    echo "--- 時刻変更前 ---\n";
    echo "現在の設定日時 (タイムゾーン: {$newYorkTimezone->getName()}): " . $dateTime->format('Y-m-d H:i:s.u P') . PHP_EOL;

    // 3. date_time_set 関数を使って、DateTime オブジェクトの時刻部分を設定します。
    //    この関数は日付部分を変更せず、時刻のみを変更します。
    //    引数: DateTime $object, int $hour, int $minute, int $second = 0, int $microsecond = 0
    $hour = 15;        // 設定する時 (0-23)
    $minute = 30;      // 設定する分 (0-59)
    $second = 45;      // 設定する秒 (0-59)
    $microsecond = 123456; // 設定するマイクロ秒 (0-999999)

    // date_time_set は元の $dateTime オブジェクトを変更し、そのオブジェクト自体を返します。
    date_time_set($dateTime, $hour, $minute, $second, $microsecond);

    echo "\n--- 時刻変更後 ---\n";
    echo "時刻変更後の日時 (タイムゾーン: {$newYorkTimezone->getName()}): " . $dateTime->format('Y-m-d H:i:s.u P') . PHP_EOL;

    // 4. 設定された時刻が、異なるタイムゾーンではどのように表示されるかを確認します。
    //    DateTime オブジェクトのタイムゾーンを変更しても、設定された「特定の瞬間」は変わりません。
    //    表示される時刻の文字列だけが、新しいタイムゾーンに合わせて調整されます。
    $tokyoTimezone = new DateTimeZone('Asia/Tokyo');
    $dateTime->setTimezone($tokyoTimezone); // DateTime オブジェクトのタイムゾーンを変更

    echo "\n--- タイムゾーン変更後 (東京時間) ---\n";
    echo "タイムゾーン変更後の日時 (タイムゾーン: {$tokyoTimezone->getName()}): " . $dateTime->format('Y-m-d H:i:s.u P') . PHP_EOL;
}

// 上記で定義した関数を実行します。
demonstrateDateTimeSetWithTimezone();

PHPのdate_time_set関数は、既存のDateTimeオブジェクトの日付部分を維持したまま、時刻（時、分、秒、マイクロ秒）を設定するための機能です。この関数は、第一引数に操作したいDateTimeオブジェクトを受け取り、第二引数以降で設定したい時、分、秒、マイクロ秒をそれぞれ整数で指定します。関数は、渡されたDateTimeオブジェクト自体を変更し、その変更されたDateTimeオブジェクトを戻り値として返します。

サンプルコードでは、まずAmerica/New_Yorkタイムゾーンで現在の時刻を持つDateTimeオブジェクトを初期化しています。その後、date_time_set関数を用いて、このオブジェクトの時刻部分を例えば「15時30分45秒123456マイクロ秒」に設定します。この際、日付は元のまま保持され、時刻のみが指定された値に更新されます。

次に、設定後のDateTimeオブジェクトのタイムゾーンをAsia/Tokyoに変更しています。ここで重要な点は、date_time_setで設定された「特定の瞬間」が変更されるわけではない、ということです。DateTimeオブジェクトに設定されているタイムゾーンを変更すると、その「特定の瞬間」が新しいタイムゾーンでは何時になるかという表示上の時刻が自動的に調整されます。これにより、date_time_setが時刻部分のみを設定し、タイムゾーンの解釈はDateTimeオブジェクトが持つタイムゾーン設定に依存することが理解できます。この関数は、日付を変更せずに時刻だけを効率的に調整したい場合に役立ちます。