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

<?php

/**
 * 現在の時刻に指定した時間を加算するサンプルコード。
 * date_add 関数を使用して、DateTime オブジェクトに DateInterval オブジェクトで定義された期間を加算します。
 */

// 1. 現在の時刻を表す DateTime オブジェクトを作成します。
$currentDateTime = new DateTime();
echo "現在の時刻: " . $currentDateTime->format('Y-m-d H:i:s') . "\n";

// 2. 加算したい時間を表す DateInterval オブジェクトを作成します。
// 例: 'PT3H' は「期間（Period）の3時間（Time 3 Hours）」を意味します。
// ここでは、3時間を加算するように設定します。
$hoursToAdd = new DateInterval('PT3H');

// 3. date_add 関数を使用して、現在の DateTime オブジェクトに時間を加算します。
// date_add は、最初の引数として渡された DateTime オブジェクト自体を変更し、
// 変更された DateTime オブジェクトを返します（失敗した場合は false）。
$modifiedDateTime = date_add($currentDateTime, $hoursToAdd);

// 4. 加算処理の成否を確認し、結果を表示します。
if ($modifiedDateTime === false) {
    echo "日付の加算に失敗しました。\n";
} else {
    // $modifiedDateTime は、$currentDateTime と同じオブジェクトを参照しています。
    echo "3時間後の時刻: " . $modifiedDateTime->format('Y-m-d H:i:s') . "\n";
}

?>

PHPのdate_add関数は、指定されたDateTimeオブジェクトに特定の期間を加算するために使用される関数です。システムエンジニアを目指す方にとって、日時を扱う処理は頻繁に発生するため、この関数は非常に役立ちます。

サンプルコードでは、まずnew DateTime()を使って現在の時刻をDateTimeオブジェクトとして取得します。次に、加算したい時間を定義するためにDateIntervalオブジェクトを作成します。例えば、new DateInterval('PT3H')は「3時間」という期間を示し、「期間（P）の（T）3時間（3H）」を意味する書式です。

date_add関数は、引数として加算対象となるDateTimeオブジェクトと、加算する期間を表すDateIntervalオブジェクトを受け取ります。この関数の重要な挙動として、渡された最初のDateTimeオブジェクト自体が直接変更される点が挙げられます。そして、変更後のDateTimeオブジェクトが戻り値として返されますが、日付の加算処理に失敗した場合はfalseを返します。

そのため、処理の成否を確認するために、戻り値がfalseでないかをチェックすることが推奨されます。成功していれば、変更後の日時をformat()メソッドで整形して表示することで、現在時刻に指定した時間が正しく加算された結果を確認できます。このように、date_add関数を使うことで、PHPで簡単に日時の加算処理を実装することが可能です。

<?php

/**
 * Demonstrates how to use the date_add function in PHP,
 * specifically highlighting its interaction with timezones and Daylight Saving Time (DST).
 *
 * This function creates a DateTime object with a specific timezone,
 * adds a DateInterval to it using date_add, and displays the results,
 * showing how date arithmetic automatically adjusts for DST changes.
 *
 * @return void
 */
function demonstrateDateAddWithTimezone(): void
{
    // 1. Create a DateTime object initialized to a specific date and timezone.
    //    We choose a date and timezone that will experience a Daylight Saving Time (DST)
    //    transition within the interval we plan to add.
    //    For 'Europe/Berlin', DST typically ends on the last Sunday of October,
    //    when clocks go back from 03:00 CEST (UTC+2) to 02:00 CET (UTC+1).
    $initialDateTime = new DateTime('2023-10-29 01:00:00', new DateTimeZone('Europe/Berlin'));

    echo "Original DateTime: " . $initialDateTime->format('Y-m-d H:i:s T (P)') . "\n";
    echo "    (Note: At this specific time, Berlin is in CEST, which is UTC+2.)\n\n";

    // 2. Create a DateInterval object to define the duration to add.
    //    Adding 3 hours from 01:00 will cause the calculation to cross the
    //    DST boundary (03:00 CEST reverting to 02:00 CET).
    $intervalToAdd = new DateInterval('PT3H'); // PT3H means "Period Time 3 Hours"

    echo "DateInterval to add: " . $intervalToAdd->format('%H hours') . "\n\n";

    // 3. Use date_add to add the interval to the DateTime object.
    //    This function modifies the $initialDateTime object directly and returns it.
    //    It correctly handles timezone rules, including DST changes.
    $resultDateTime = date_add($initialDateTime, $intervalToAdd);

    // Always check if the operation was successful, as date_add can return false on failure.
    if ($resultDateTime === false) {
        echo "Error: Failed to add the date interval.\n";
        return;
    }

    // 4. Display the modified DateTime object and its timezone information.
    echo "Modified DateTime: " . $resultDateTime->format('Y-m-d H:i:s T (P)') . "\n";
    echo "    (Note: After the addition, Berlin is in CET, which is UTC+1, due to the DST change.)\n";
    echo "    The 3-hour addition correctly accounts for the clock going back one hour at 03:00 CEST,\n";
    echo "    resulting in a 3-hour perceived duration across the timezone shift.\n";
}

// Execute the demonstration function.
demonstrateDateAddWithTimezone();

PHPのdate_add関数は、既存のDateTimeオブジェクトに特定の日時期間を加算するための機能です。この関数は、第一引数に加算の対象となるDateTimeオブジェクトを、第二引数に加算したい期間を表すDateIntervalオブジェクトを受け取ります。date_addは、指定されたDateTimeオブジェクト自体を変更し、その変更されたDateTimeオブジェクトを返します。もし加算処理が失敗した場合はfalseを返します。

サンプルコードでは、date_addがタイムゾーンと夏時間（DST）の切り替えを自動的に考慮して日時計算を行う様子を具体的に示しています。特定のタイムゾーン（例: 'Europe/Berlin'）で夏時間から通常時間へ移行する日時を設定し、そこに3時間の期間を加算することで、時計が1時間戻るDSTの調整が自動的に行われ、正しく加算後の日時が計算されることが確認できます。これにより、複雑なタイムゾーンの変更時でも、開発者が手動で調整することなく正確な日時計算を行えることがわかります。関数の戻り値がfalseでないかを常に確認する習慣は、エラーに強いプログラムを作成する上で重要です。