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

Copy
1<?php
2
3/**
4 * 現在の日付と時刻を様々な形式でフォーマットして表示する関数。
5 *
6 * DateTimeInterface::format メソッドを使用して、日付と時刻の表示形式をカスタマイズします。
7 *
8 * @return void
9 */
10function displayFormattedDates(): void
11{
12    // 現在の日付と時刻を表すDateTimeオブジェクトを作成します。
13    // DateTimeInterfaceはインターフェースなので、DateTimeクラスを実装に使用します。
14    $currentDateTime = new DateTime();
15
16    echo "--- 日付と時刻のフォーマット例 ---\n\n";
17
18    // 例1: 年-月-日 (YYYY-MM-DD) 形式
19    // Y: 4桁の年, m: 2桁の月 (01-12), d: 2桁の日 (01-31)
20    echo "基本の日付形式 (YYYY-MM-DD): " . $currentDateTime->format('Y-m-d') . "\n";
21
22    // 例2: 曜日, 月 日, 年 (例: Monday, January 1, 2023) 形式
23    // l (小文字のL): 曜日の完全なテキスト形式, F: 月の完全なテキスト形式
24    echo "読みやすい日付形式: " . $currentDateTime->format('l, F d, Y') . "\n";
25
26    // 例3: 時:分:秒 (HH:MM:SS) 形式 (24時間表記)
27    // H: 2桁の時 (00-23), i: 2桁の分 (00-59), s: 2桁の秒 (00-59)
28    echo "時刻形式 (HH:MM:SS): " . $currentDateTime->format('H:i:s') . "\n";
29
30    // 例4: 日本語のフル表記 (YYYY年MM月DD日 HH時II分SS秒)
31    echo "日本語のフル表記: " . $currentDateTime->format('Y年m月d日 H時i分s秒') . "\n";
32
33    // 例5: ISO 8601 形式 (APIやデータベースでよく使用される国際標準)
34    // DateTime::ISO8601 定数を使用すると、特定のフォーマット文字列を覚えずに済みます。
35    echo "ISO 8601 形式: " . $currentDateTime->format(DateTime::ISO8601) . "\n";
36
37    // 例6: Unixタイムスタンプ (1970年1月1日 00:00:00 UTCからの秒数)
38    // U: Unixタイムスタンプ
39    echo "Unixタイムスタンプ: " . $currentDateTime->format('U') . "\n";
40}
41
42// 上記の関数を実行して、結果を出力します。
43displayFormattedDates();
44

PHP 8のDateTimeInterface::formatメソッドは、日付と時刻の情報を、指定された書式に沿った文字列として取得するために使用されます。DateTimeInterfaceは日付と時刻を扱うためのインターフェースであり、通常はそれを実装したDateTimeクラスのインスタンスを通じて利用します。

このメソッドはstring $formatという引数を一つ取ります。この$format引数には「フォーマット文字列」と呼ばれる特別な文字の組み合わせを指定し、これによって年、月、日、時、分、秒、曜日などをどのように表示するかを自由に制御できます。例えば、「Y」は4桁の年、「m」は2桁の月、「d」は2桁の日を表し、これらを「Y-m-d」のように組み合わせることで「YYYY-MM-DD」形式の文字列を生成できます。その他にも、24時間表記の「H」、分を表す「i」、秒を表す「s」など、多様な指定子が存在します。国際標準であるISO 8601形式や、Unixタイムスタンプを取得するための指定子も利用可能です。

メソッドの戻り値は、フォーマットに成功した場合は日付と時刻を表すstring型の文字列です。フォーマットに失敗した場合にはfalseが返されます。

サンプルコードでは、現在の日付と時刻を表すDateTimeオブジェクトを作成し、formatメソッドに様々なフォーマット文字列を渡すことで、日付や時刻が多様な形式で表示される様子を示しています。「Y-m-d」のような基本的な形式から、「l, F d, Y」のような読みやすい形式、さらには「Y年m月d日 H時i分s秒」のように日本語を混ぜた形式まで、簡単にカスタマイズして出力できることが分かります。この機能は、ウェブアプリケーションでユーザーに日付を表示したり、API連携やデータベースへの保存のために特定の形式に変換したりする際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * 現在の日付と時刻を様々な書式で表示するサンプル関数。
5 * DateTimeInterface::format メソッドの使用例を示します。
6 *
7 * @return void
8 */
9function showFormattedDates(): void
10{
11    // 現在のシステム時刻に基づいてDateTimeImmutableオブジェクトを作成します。
12    // DateTimeImmutableは、オブジェクトの値を変更しない（不変である）ため推奨されます。
13    $now = new DateTimeImmutable();
14
15    echo "--- 日付/時刻のフォーマット例 ---\n\n";
16
17    // format() メソッドを使用して、DateTimeオブジェクトを様々な書式で文字列に変換します。
18    // 引数には、日付/時刻の各要素を表す書式文字（例: Y, m, d, H, i, sなど）を含む文字列を渡します。
19    // PHP公式ドキュメントで全ての書式文字を確認できます。
20
21    // 例1: 標準的な「年-月-日 時:分:秒」形式
22    $format1 = 'Y-m-d H:i:s';
23    $formattedDate1 = $now->format($format1);
24    // format()は失敗した場合にfalseを返しますが、有効な書式文字列であれば通常は文字列を返します。
25    if ($formattedDate1 !== false) {
26        echo "標準書式 ({$format1}): " . $formattedDate1 . "\n";
27    }
28
29    // 例2: 日本でよく使われる「年/月/日」形式
30    $format2 = 'Y/m/d';
31    $formattedDate2 = $now->format($format2);
32    if ($formattedDate2 !== false) {
33        echo "年/月/日書式 ({$format2}): " . $formattedDate2 . "\n";
34    }
35
36    // 例3: 時間のみ（「時:分:秒」）
37    $format3 = 'H:i:s';
38    $formattedDate3 = $now->format($format3);
39    if ($formattedDate3 !== false) {
40        echo "時間書式 ({$format3}): " . $formattedDate3 . "\n";
41    }
42
43    // 例4: 曜日、月名、日、年、12時間制の時:分 午前/午後
44    $format4 = 'D, M j, Y, g:i a'; // 例: Fri, Oct 27, 2023, 10:30 am
45    $formattedDate4 = $now->format($format4);
46    if ($formattedDate4 !== false) {
47        echo "詳細書式 ({$format4}): " . $formattedDate4 . "\n";
48    }
49
50    // 例5: ISO 8601フォーマット（システム間でのデータ交換によく使われます）
51    $format5 = 'c'; // 例: 2023-10-27T10:30:45+09:00
52    $formattedDate5 = $now->format($format5);
53    if ($formattedDate5 !== false) {
54        echo "ISO 8601書式 ({$format5}): " . $formattedDate5 . "\n";
55    }
56
57    echo "\n--- 終了 ---\n";
58}
59
60// 関数を実行して、日付/時刻の書式設定の出力例を確認します。
61showFormattedDates();

PHPのDateTimeInterface::formatメソッドは、日付と時刻の情報を、指定された書式で人間が読みやすい文字列に変換するために使用されます。このメソッドは、DateTimeImmutableなどの日付/時刻オブジェクトから呼び出すことで利用できます。

引数$formatには、年（Y）、月（m）、日（d）、時（H）、分（i）、秒（s）といった日付/時刻の各要素を表す特別な文字を組み合わせた文字列を渡します。これにより、日付の表示形式を自由にカスタマイズすることが可能です。例えば、'Y-m-d H:i:s'という書式を指定すると「2023-10-27 10:30:45」のように出力されます。

戻り値は、フォーマットに成功した場合は指定された書式の日付/時刻を表す文字列が返されます。書式が不正であるなどの理由で失敗した場合はfalseが返されることがあります。

サンプルコードでは、まず現在のシステム時刻をDateTimeImmutableオブジェクトとして取得し、そのオブジェクトに対してformat()メソッドを様々な$format引数で呼び出しています。これにより、標準的な「年-月-日 時:分:秒」形式、日本で一般的な「年/月/日」形式、ISO 8601形式など、目的に応じた多様な日付/時刻の表示方法が実現できることが示されています。システム開発において、ユーザーインターフェースやログ出力など、日付/時刻の表示を柔軟に制御したい場合に非常に便利な機能です。