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

<?php

// 日付の差を計算する例です。
// DateTimeオブジェクトを作成します。
$datetime1 = new DateTime('2023-01-01'); // 最初のDateTimeオブジェクト
$datetime2 = new DateTime('2024-03-15'); // 2番目のDateTimeオブジェクト

// date_diff() 関数を使用して、2つの日付の差を計算します。
// この関数はDateIntervalオブジェクトを返します。
// 第3引数 $absolute はデフォルトで false ですが、true に設定すると常に正の差を返します。
$interval = date_diff($datetime1, $datetime2);

// 計算結果であるDateIntervalオブジェクトから日付の差を表示します。
// format() メソッドは、指定された書式で期間を表現するのに便利です。
// %y: 年, %m: 月, %d: 日
echo "日付1: " . $datetime1->format('Y-m-d') . "\n";
echo "日付2: " . $datetime2->format('Y-m-d') . "\n";
echo "日付の差: " . $interval->format('%y 年 %m ヶ月 %d 日') . "\n";

// 別の例: 日付の順序が逆の場合
$datetimeA = new DateTime('2024-03-15');
$datetimeB = new DateTime('2023-01-01');

// $absolute を true に設定して、常に正の差を取得します。
$intervalAbsolute = date_diff($datetimeA, $datetimeB, true);

echo "\n--- $absolute パラメータが true の場合 ---\n";
echo "日付A: " . $datetimeA->format('Y-m-d') . "\n";
echo "日付B: " . $datetimeB->format('Y-m-d') . "\n";
echo "日付の差 (絶対値): " . $intervalAbsolute->format('%y 年 %m ヶ月 %d 日') . "\n";

?>

date_diff()関数は、2つの日付の差を精密に計算するためのPHP関数です。この関数は、比較したい2つの日付を表すDateTimeオブジェクトを引数として受け取ります。最初の2つの引数に、new DateTime('2023-01-01')のようにして作成したオブジェクトを渡します。第3引数である$absoluteにtrueを指定すると、日付の前後関係にかかわらず、常に正の値（絶対値）として差が計算されます。指定しない場合のデフォルトはfalseです。

この関数の戻り値は、計算結果を保持するDateIntervalオブジェクトです。このオブジェクトには、年、月、日、時、分、秒といった単位で2つの日付の差が格納されています。

結果を表示するには、DateIntervalオブジェクトが持つformat()メソッドが便利です。$interval->format('%y 年 %m ヶ月 %d 日')のように書式を指定することで、「1年 2ヶ月 14日」といった人間が読みやすい形式の文字列として差を取り出すことができます。

<?php

/**
 * Calculates the total difference in minutes between two DateTimeInterface objects.
 *
 * This function uses date_diff to get a DateInterval object, then extracts
 * the total days, hours, and minutes from it to compute the total duration in minutes.
 * The difference is always returned as a positive integer (absolute difference).
 *
 * @param DateTimeInterface $datetime1 The first date/time object.
 * @param DateTimeInterface $datetime2 The second date/time object.
 * @return int The absolute total difference in minutes.
 */
function calculateDateDifferenceInMinutes(DateTimeInterface $datetime1, DateTimeInterface $datetime2): int
{
    // date_diff関数を使用して2つの日付時刻オブジェクト間の差を計算します。
    // 第3引数にtrueを渡すことで、常に正の期間（絶対差）が返されます。
    $interval = date_diff($datetime1, $datetime2, true);

    $totalMinutes = 0;

    // DateIntervalオブジェクトの'days'プロパティは、2つの日付間の合計日数を提供します。
    // これは、正確な合計分数計算のために不可欠です。
    if ($interval->days !== false) {
        $totalMinutes += $interval->days * 24 * 60; // 合計日数を分に変換して加算
    }

    $totalMinutes += $interval->h * 60; // 時間コンポーネントを分に変換して加算
    $totalMinutes += $interval->i;      // 分コンポーネントを直接加算

    return $totalMinutes;
}

// --- 単体で動作可能なサンプルコードの例 ---
// CLI環境で実行された場合のみ、以下のコードが実行されます。
if (php_sapi_name() === 'cli') {
    // 例1: 異なる日付と時間の差を計算
    $date1 = new DateTime('2023-10-26 10:00:00');
    $date2 = new DateTime('2023-10-27 11:30:00'); // date1から1日1時間30分後

    $minutesDifference1 = calculateDateDifferenceInMinutes($date1, $date2);
    echo "差: {$date1->format('Y-m-d H:i:s')} と {$date2->format('Y-m-d H:i:s')} は {$minutesDifference1} 分です。\n"; // 出力: 1530分

    // 例2: 同じ日付内で時間が逆順の差を計算
    $date3 = new DateTime('2023-10-28 09:15:00');
    $date4 = new DateTime('2023-10-28 08:00:00'); // date3から1時間15分前

    $minutesDifference2 = calculateDateDifferenceInMinutes($date3, $date4);
    echo "差: {$date3->format('Y-m-d H:i:s')} と {$date4->format('Y-m-d H:i:s')} は {$minutesDifference2} 分です。\n"; // 出力: 75分

    // 例3: ちょうど1年の差を計算 (うるう年ではない期間を想定)
    $date5 = new DateTime('2023-01-01 00:00:00');
    $date6 = new DateTime('2024-01-01 00:00:00'); // date5からちょうど1年後 (365日)

    $minutesDifference3 = calculateDateDifferenceInMinutes($date5, $date6);
    echo "差: {$date5->format('Y-m-d H:i:s')} と {$date6->format('Y-m-d H:i:s')} は {$minutesDifference3} 分です。\n"; // 出力: 525600分 (365日 * 24時間 * 60分)
}

このPHPのサンプルコードは、二つの日時（DateTimeInterfaceオブジェクト）の間の時間を合計何分であるかを計算する方法を解説しています。中心となるのはdate_diff関数で、この関数は二つの日時オブジェクト（$datetime1と$datetime2）を受け取り、それらの差をDateIntervalオブジェクトとして返します。引数$absoluteにtrueを指定することで、日時の前後関係に関わらず、常に差を正の期間として取得できます。戻り値であるDateIntervalオブジェクトには、差の日数（days）、時間（h）、分（i）などの情報が格納されています。サンプルコードでは、このDateIntervalオブジェクトから、合計の日数を分に、時間を分にそれぞれ変換し、さらに残りの分を加えて、最終的な合計分数を算出しています。これにより、何日も離れた日時であっても、時間や分のずれを含めて、正確な合計時間を分単位で把握することができます。コードの最後には、具体的な日時オブジェクトを作成し、計算結果を表示する例が示されており、関数の動作をわかりやすく理解できます。