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

Copy
1<?php
2
3// DateTimeImmutable クラスは、日付と時刻の情報を変更不能なオブジェクトとして扱います。
4// new DateTimeImmutable() で、現在の日付と時刻を持つオブジェクトを作成します。
5$currentDateTime = new DateTimeImmutable();
6
7echo "現在の日付と時刻を様々な形式で表示します。\n\n";
8
9// format() メソッドは、日付/時刻オブジェクトを特定の書式文字列に変換します。
10// 引数には、PHPのdate()関数と同様の書式指定文字（例: 'Y', 'm', 'd', 'H', 'i', 's'）を渡します。
11
12// 例1: 一般的な YYYY-MM-DD HH:MM:SS 形式
13// 'Y': 西暦年 (4桁), 'm': 月 (2桁), 'd': 日 (2桁)
14// 'H': 時 (24時間形式), 'i': 分, 's': 秒
15$format1 = 'Y-m-d H:i:s';
16$formattedString1 = $currentDateTime->format($format1);
17echo "書式 '{$format1}': " . $formattedString1 . "\n";
18
19// 例2: Month Day, Year HH:MM AM/PM 形式
20// 'F': 月の名称 (例: January), 'j': 日 (先頭のゼロなし)
21// 'Y': 西暦年 (4桁), 'g': 時 (12時間形式、先頭のゼロなし), 'i': 分
22// 'a': 午前/午後 (小文字、例: am/pm)
23$format2 = 'F j, Y, g:i a';
24$formattedString2 = $currentDateTime->format($format2);
25echo "書式 '{$format2}': " . $formattedString2 . "\n";
26
27// 例3: ISO 8601 形式 (国際標準化機構が定めた日付と時刻の表記法)
28// 'c' または DateTimeInterface::ISO8601 定数を使用します。
29// これは、日付と時刻を交換するための標準的な形式です。
30$format3 = 'c'; // または DateTimeInterface::ISO8601
31$formattedString3 = $currentDateTime->format($format3);
32echo "書式 '{$format3}' (ISO 8601): " . $formattedString3 . "\n";
33
34// 特定の日付を設定してフォーマットする例
35// 引数に日付文字列を渡して特定のDateTimeImmutableオブジェクトを作成できます。
36$specificDate = new DateTimeImmutable('2023-01-15 10:30:00');
37$specificFormat = 'Y年m月d日 H時i分です';
38$formattedSpecificDate = $specificDate->format($specificFormat);
39echo "\n特定の日付 '2023-01-15 10:30:00' のフォーマット:\n";
40echo "書式 '{$specificFormat}': " . $formattedSpecificDate . "\n";
41
42?>

PHPのDateTimeImmutableクラスは、日付と時刻の情報を、一度作成したら内容が変更できない「変更不能なオブジェクト」として扱います。このDateTimeImmutableオブジェクトに用意されているformatメソッドは、保持している日付と時刻の情報を、指定された書式に従って整形された文字列に変換するために使用されます。

formatメソッドは、string $formatという引数を一つ受け取ります。この引数には、日付や時刻をどのように表示したいかを指定する「書式文字列」を渡します。書式文字列の中では、Y（西暦年）、m（月）、d（日）、H（時）、i（分）、s（秒）といった特定の文字を組み合わせることで、日付や時刻の各要素の表示形式を細かく指定できます。例えば、'Y-m-d H:i:s'と指定すれば「YYYY-MM-DD HH:MM:SS」形式の文字列が得られ、'F j, Y, g:i a'と指定すれば「月名 日, 年, 時:分 AM/PM」のような読みやすい形式になります。国際標準のISO 8601形式で出力したい場合は、'c'という短い書式文字を使用することも可能です。

メソッドの戻り値は、引数で指定した書式に従って整形された日付と時刻を表すstring（文字列）型です。このようにformatメソッドを活用することで、DateTimeImmutableオブジェクトの日付と時刻を、システムの要件やユーザーインターフェースに合わせて柔軟に表示することができます。

Copy
1<?php
2
3/**
4 * DateTimeImmutable::format メソッドの基本的な使用例を示す関数です。
5 * この関数は、現在の日付と時刻を異なるフォーマットで表示します。
6 *
7 * @return void
8 */
9function displayFormattedDates(): void
10{
11    // 現在の日付と時刻を表すDateTimeImmutableオブジェクトを作成します。
12    // DateTimeImmutableは、一度作成されるとその値が変更されない（不変）日付/時刻オブジェクトです。
13    $currentDateTime = new DateTimeImmutable();
14
15    echo "--- 現在の日付と時刻のフォーマット例 ---\n";
16
17    // よく使用される標準的なフォーマット (年-月-日 時:分:秒)
18    echo "標準日時 (Y-m-d H:i:s): " . $currentDateTime->format('Y-m-d H:i:s') . "\n";
19
20    // 読みやすい日付形式 (例: January 20, 2024)
21    echo "読みやすい日付 (F j, Y): " . $currentDateTime->format('F j, Y') . "\n";
22
23    // ISO 8601 形式 (国際標準の日付時刻形式)
24    echo "ISO 8601 形式: " . $currentDateTime->format(DateTimeInterface::ISO8601) . "\n";
25
26    // 曜日名のみ
27    echo "曜日名 (l): " . $currentDateTime->format('l') . "\n";
28
29    // 時刻のみ (時:分)
30    echo "時刻のみ (H:i): " . $currentDateTime->format('H:i') . "\n";
31
32    // 年月日 (スラッシュ区切り)
33    echo "年月日 (Y/m/d): " . $currentDateTime->format('Y/m/d') . "\n";
34
35    // Unixタイムスタンプ (1970年1月1日 00:00:00 UTCからの秒数)
36    echo "Unixタイムスタンプ (U): " . $currentDateTime->format('U') . "\n";
37
38    echo "\n--- 特定の日付と時刻のフォーマット例 ---\n";
39
40    // 特定の日付と時刻を指定してDateTimeImmutableオブジェクトを作成します。
41    $specificDateTime = new DateTimeImmutable('2023-01-15 14:30:00');
42
43    // 指定した日付を標準日時形式でフォーマット
44    echo "指定日時 (Y-m-d H:i:s): " . $specificDateTime->format('Y-m-d H:i:s') . "\n";
45
46    // 指定した日付を別の形式でフォーマット
47    echo "指定日時 (g:i A, M j, Y): " . $specificDateTime->format('g:i A, M j, Y') . "\n";
48}
49
50// 上記の関数を実行し、フォーマットされた日付と時刻を表示します。
51displayFormattedDates();
52
53?>

DateTimeImmutable::formatメソッドは、PHPで日付や時刻の情報を、指定した書式（フォーマット）の文字列として取得するための重要な機能です。このメソッドが所属するDateTimeImmutableクラスは、一度作成された日時情報を変更できない「不変」なオブジェクトとして扱います。

formatメソッドは、引数としてstring $formatを受け取ります。この$formatには、年、月、日、時、分、秒、曜日などを表す特定の「書式指定子」を組み合わせた文字列を指定します。例えば、「Y-m-d H:i:s」は「2024-01-20 15:30:00」のような形式を、「F j, Y」は「January 20, 2024」のような形式を意味します。戻り値は、指定された書式に従って整形された日付時刻のstring型データです。

サンプルコードでは、まずnew DateTimeImmutable()で現在の日時を表すオブジェクトを作成し、続けて$currentDateTime->format('Y-m-d H:i:s')のように、様々な書式指定子を使って現在の日時を整形して表示しています。また、new DateTimeImmutable('2023-01-15 14:30:00')のように、特定の日時を指定してオブジェクトを作成し、それを異なるフォーマットで出力する例も示されています。このメソッドは、システム開発において、日時表示の柔軟な制御を可能にします。

Copy
1<?php
2
3// DateTimeImmutable オブジェクトを作成します。
4// 引数を省略すると、現在の日付と時刻が設定されます。
5$now = new DateTimeImmutable();
6
7// 現在の日付と時刻を様々な形式で文字列にフォーマットして表示します。
8echo "現在の日付と時刻を様々な形式で表示します。\n";
9echo "----------------------------------------\n";
10
11// YYYY-MM-DD HH:MM:SS 形式 (例: 2023-10-27 10:30:00)
12// データベースに格納する際などによく使われる形式です。
13echo "標準の日付時刻形式: " . $now->format('Y-m-d H:i:s') . "\n";
14
15// 月 日, 年 HH:MM am/pm 形式 (例: October 27, 2023, 10:30 am)
16// 人間が読みやすい形式です。
17echo "読みやすい日付時刻形式: " . $now->format('F j, Y, g:i a') . "\n";
18
19// ISO 8601 形式 (例: 2023-10-27T10:30:00+09:00)
20// 日付と時刻の国際標準形式で、異なるシステム間でのデータ交換によく使われます。
21echo "ISO 8601 形式: " . $now->format(DateTimeInterface::ISO8601) . "\n";
22
23// Unix タイムスタンプ (例: 1672531200)
24// 1970年1月1日 00:00:00 UTC からの秒数で、内部処理などで利用されます。
25echo "Unix タイムスタンプ: " . $now->format('U') . "\n";
26
27// 特定の要素のみを表示する例（曜日、英語）
28echo "曜日のみ（英語）: " . $now->format('l') . "\n";
29
30?>

PHP 8のDateTimeImmutableクラスに属するformatメソッドは、日付と時刻の情報を、指定された書式に沿った文字列に変換するための機能を提供します。このメソッドは、引数としてstring $formatを受け取ります。この引数には、年、月、日、時、分、秒といった日付の各要素をどのように表現するかを指示する特別な文字（フォーマット指定子）を組み合わせて指定します。メソッドが実行されると、そのフォーマットに基づいて整形された日付と時刻の文字列が、戻り値として返されます。

サンプルコードでは、まず引数なしで現在の時刻が設定されたDateTimeImmutableオブジェクトを作成しています。このオブジェクトのformatメソッドを使うことで、同じ日付情報から様々な表示形式の文字列を生成できます。例えば、'Y-m-d H:i:s'は「2023-10-27 10:30:00」のように、データベースへの格納によく使われる標準的な形式を出力します。また、'F j, Y, g:i a'は「October 27, 2023, 10:30 am」のような、人間が読みやすい形式に整形します。

国際標準であるISO 8601形式を生成する場合は、DateTimeInterface::ISO8601定数をformatメソッドに渡すことで、異なるシステム間でのデータ交換に適した文字列が得られます。さらに、'U'を指定すると、1970年1月1日からの経過秒数を表すUnixタイムスタンプが出力され、内部的な時刻処理に利用されます。このように、formatメソッドは、日付や時刻の表示形式を柔軟に制御し、様々なシステム要件やユーザーインターフェースに対応した出力文字列を簡単に生成できる非常に便利なメソッドです。