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

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）を表示する形式など、様々な書式指定子を用いて間隔情報を出力しています。これにより、日付や時間の計算結果を柔軟かつ明確に表現することが可能になります。システムエンジニアにとって、ログの記録やレポートの生成など、日時データを整形して表示する場面で非常に役立つ機能です。