【PHP8.x】DateInterval::format()メソッドの使い方

Copy
1<?php
2
3/**
4 * 2つの日付間の差を計算し、指定されたフォーマットで表示する関数
5 *
6 * @param DateTime $date1 比較する最初のDateTimeオブジェクト
7 * @param DateTime $date2 比較する2番目のDateTimeオブジェクト
8 * @param string $format DateInterval::format() メソッドに渡すフォーマット文字列
9 * @return string フォーマットされた日付の差
10 */
11function displayDateDifference(DateTime $date1, DateTime $date2, string $format): string
12{
13    // 2つの日付間の差を計算し、DateIntervalオブジェクトを取得
14    $interval = $date1->diff($date2);
15
16    // DateIntervalオブジェクトを、指定されたフォーマット文字列で整形
17    // '%y' は年、'%m' は月、'%d' は日、'%h' は時間、'%i' は分、'%s' は秒を表します。
18    return $interval->format($format);
19}
20
21// 現在の日時を取得
22$now = new DateTime();
23
24// 未来の特定の日時を設定（例: 今から約1年3ヶ月と少し未来）
25$futureDate = new DateTime('2025-06-15 10:30:00');
26
27// 日付の差を「X年 Yヶ月 Z日 H時間 I分 S秒」の形式で表示
28$formattedDifference = displayDateDifference(
29    $now,
30    $futureDate,
31    '%y年 %mヶ月 %d日 %h時間 %i分 %s秒'
32);
33
34// 結果を出力
35echo "現在の日時: " . $now->format('Y-m-d H:i:s') . "\n";
36echo "未来の日時: " . $futureDate->format('Y-m-d H:i:s') . "\n";
37echo "両者の差: " . $formattedDifference . "\n";
38
39?>

PHP 8のDateInterval::formatメソッドは、2つの日付や時刻の「差」を表すDateIntervalオブジェクトを、指定された書式で整形し、文字列として取得するために使用されます。

まず、DateIntervalオブジェクトは、DateTimeオブジェクトのdiff()メソッドを使って、2つの日付間の差を計算することで生成されます。このDateIntervalオブジェクトには、年、月、日、時、分、秒といった差の情報が含まれています。

formatメソッドは、このDateIntervalオブジェクトが持つ差の情報を、人間にとって読みやすい形式に変換する役割を担います。引数$formatには、整形したい文字列のパターンを指定します。このパターンの中には、%y（年）、%m（月）、%d（日）、%h（時間）、%i（分）、%s（秒）といった特別な指定子を含めることができます。これらの指定子は、DateIntervalオブジェクトが持つそれぞれの差の数値に置き換えられます。また、これらの指定子の間に任意の文字列（例：「年」、「ヶ月」など）を自由に挿入することで、より柔軟な表現が可能です。

このメソッドの戻り値は、指定されたフォーマットに従って整形された日付の差を表す文字列です。サンプルコードでは、現在の日時と未来の日時の差を計算し、'%y年 %mヶ月 %d日 %h時間 %i分 %s秒'というフォーマットで整形して表示しています。これにより、「1年 3ヶ月 20日 5時間 10分 30秒」のように、具体的な日付の差を分かりやすく表現できるのです。この機能は、イベントまでの残り時間表示や、経過時間の計算など、様々な場面で活用できます。

Copy
1<?php
2
3/**
4 * DateInterval::format() メソッドの使用例を示します。
5 * このメソッドは、2つの日時間の間隔（差）を、指定されたフォーマットで文字列に整形します。
6 * システムエンジニアを目指す初心者の方にも、日付や時間の計算結果を
7 * 読みやすい形式で出力する方法を理解してもらうことを目的としています。
8 */
9function demonstrateDateIntervalFormat(): void
10{
11    // 比較する開始日時と終了日時を作成します。
12    // DateTimeオブジェクトは、日付と時間の情報を保持します。
13    $startDateTime = new DateTime('2023-01-01 10:00:00');
14    $endDateTime = new DateTime('2024-03-15 15:30:45');
15
16    echo "=== 日時の間隔フォーマット例 ===\n";
17    echo "開始日時: " . $startDateTime->format('Y-m-d H:i:s') . "\n";
18    echo "終了日時: " . $endDateTime->format('Y-m-d H:i:s') . "\n\n";
19
20    // DateTime::diff() メソッドを使って、2つの日時間の差を計算し、
21    // DateInterval オブジェクトとして取得します。
22    $interval = $startDateTime->diff($endDateTime);
23
24    // DateInterval::format() メソッドは、書式指定子（例: %y, %m, %d）を使って
25    // 間隔の各要素（年、月、日など）を整形します。
26    // 書式指定子はパーセント記号 (%) でエスケープする必要があります。
27
28    // 1. 年、月、日、時間、分、秒をすべて表示するフォーマット
29    echo "1. 完全な間隔: " . $interval->format('%y 年 %m ヶ月 %d 日 %h 時間 %i 分 %s 秒') . "\n";
30
31    // 2. 短縮形のフォーマット
32    echo "2. 短縮形の間隔: " . $interval->format('%yY %mM %dD %hH %iM %sS') . "\n";
33
34    // 3. 間隔の総日数のみを表示するフォーマット
35    // '%a' は、間隔全体の日数を表します。
36    echo "3. 総日数: " . $interval->format('%a 日') . "\n";
37
38    // 4. 間隔の符号（正または負）を表示するフォーマット
39    // '%R' は、間隔が正 (+) か負 (-) かを示します。
40    echo "4. 間隔の符号: " . $interval->format('%R') . "\n";
41
42    // 5. 年、月、日のみを表示するフォーマット
43    echo "5. 年月日のみ: " . $interval->format('%y 年 %m ヶ月 %d 日') . "\n";
44
45    // 6. 時間、分、秒のみを表示するフォーマット
46    echo "6. 時間分秒のみ: " . $interval->format('%h 時間 %i 分 %s 秒') . "\n";
47
48    echo "\nこれらの例から、DateInterval::format() を使って\n";
49    echo "日付/時間の間隔を柔軟に表示できることがわかります。\n";
50}
51
52// 上記の関数を実行し、DateInterval::format() の動作を確認します。
53demonstrateDateIntervalFormat();
54

DateInterval::format()は、PHPで二つの日付や時間の「間隔」を表すDateIntervalオブジェクトの内容を、指定した書式で文字列として整形するためのメソッドです。この機能は、主にDateTime::diff()メソッドによって計算された日時の差を、人間が読みやすい形に変換する際に利用されます。

引数$formatには、間隔の各要素（年、月、日、時間など）を表示するための書式指定子を含む文字列を渡します。例えば、%yは年、%mは月、%dは日、%hは時間、%iは分、%sは秒を表し、パーセント記号（%）で始まり識別されます。また、%aは間隔全体の総日数、%Rは間隔が正（+）か負（-）かを示すなど、便利な書式指定子も用意されています。このメソッドは、指定された書式に従って整形された文字列を戻り値として返します。

サンプルコードでは、まず二つのDateTimeオブジェクトの差分をDateIntervalオブジェクトとして取得しています。その後、このDateIntervalオブジェクトに対してformat()メソッドを使い、「%y 年 %m ヶ月 %d 日 %h 時間 %i 分 %s 秒」のような完全な形式や、「%a 日」のように総日数のみを表示する形式、さらには間隔の符号（%R）を表示する形式など、様々な書式指定子を用いて間隔情報を出力しています。これにより、日付や時間の計算結果を柔軟かつ明確に表現することが可能になります。システムエンジニアにとって、ログの記録やレポートの生成など、日時データを整形して表示する場面で非常に役立つ機能です。

Copy
1<?php
2
3// 現在の日時を取得します。DateTimeImmutableは不変な日付オブジェクトを作成します。
4// これにより、元のオブジェクトが意図せず変更されることを防ぎます。
5$now = new DateTimeImmutable();
6
7// 現在から特定の期間後の日時を作成します。
8// 例として、現在から3年2ヶ月15日10時間5分30秒後の日時を設定します。
9$future = $now->modify('+3 years 2 months 15 days 10 hours 5 minutes 30 seconds');
10
11// 2つの日時の差分を計算し、DateIntervalオブジェクトとして取得します。
12// DateIntervalは、時間や日付の期間を表すオブジェクトです。
13$interval = $now->diff($future);
14
15// DateInterval::format() メソッドを使用して、期間を人間が読める形式に整形します。
16// 書式文字列内のパーセンテージ記号 (%) の後に続く文字は、表示する期間の要素を示します。
17// %Y: 年, %M: 月, %D: 日, %H: 時, %I: 分 (minutes), %S: 秒
18$formattedInterval = $interval->format(
19    '経過期間: %Y年 %Mヶ月 %D日 %H時間 %I分 %S秒'
20);
21
22// 整形された期間の文字列を出力します。
23echo $formattedInterval . PHP_EOL;
24

PHPのDateInterval::formatメソッドは、日付や時刻の「期間」を表すDateIntervalオブジェクトの内容を、指定した書式で文字列に整形するメソッドです。

このメソッドの引数$formatには、期間をどのように表示するかを定義する書式文字列を指定します。この書式文字列には、年を表す%Y、月を表す%M、日を表す%D、時を表す%H、分を表す%I、秒を表す%Sといったプレースホルダーを使用できます。メソッドの戻り値は、整形された期間を表す文字列です。

サンプルコードでは、まず現在の日時と、そこから特定の期間（3年2ヶ月15日10時間5分30秒）後の日時を作成し、それらの差分をDateIntervalオブジェクトとして取得しています。次に、このDateIntervalオブジェクトに対してformat()メソッドを呼び出し、「経過期間: %Y年 %Mヶ月 %D日 %H時間 %I分 %S秒」という書式を使って期間情報を人間が読みやすい文字列に変換しています。これにより、Webサイトでの残り時間表示や、システムログの期間計算結果など、複雑な期間情報を簡単に、かつ目的に合わせて表示できるようになります。