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

Copy
1<?php
2
3/**
4 * 指定されたフォーマットと日付文字列からDateTimeImmutableオブジェクトを生成し、結果を表示します。
5 *
6 * @param string $format   日付文字列の期待されるフォーマット（例: 'Y-m-d H:i:s', 'd/m/Y'）
7 * @param string $datetime 解析する日付と時刻の文字列
8 * @return void
9 */
10function createAndDisplayImmutableDateFromSpecificFormat(string $format, string $datetime): void
11{
12    // date_create_immutable_from_format関数を使用して、指定されたフォーマットで
13    // 日付文字列を解析し、DateTimeImmutableオブジェクトを生成します。
14    // 成功した場合はDateTimeImmutableオブジェクト、失敗した場合はfalseを返します。
15    $immutableDateTime = date_create_immutable_from_format($format, $datetime);
16
17    // オブジェクトの生成が成功したかを確認します。
18    // instanceof DateTimeImmutable を使用して、戻り値が正しいオブジェクト型であるかを厳密にチェックします。
19    if ($immutableDateTime instanceof DateTimeImmutable) {
20        echo "--- 成功: フォーマット '{$format}' から日付を生成 ---\n";
21        // 生成されたDateTimeImmutableオブジェクトを別のフォーマットで表示します。
22        echo "オリジナル: '{$datetime}'\n";
23        echo "解析後: " . $immutableDateTime->format('Y年m月d日 H時i分s秒') . "\n";
24        echo "タイムスタンプ: " . $immutableDateTime->getTimestamp() . "\n";
25    } else {
26        // オブジェクトの生成に失敗した場合（例: フォーマットが一致しない、無効な日付など）。
27        echo "--- 失敗: フォーマット '{$format}' から日付を生成できませんでした ---\n";
28        echo "指定された日付: '{$datetime}'\n";
29        echo "エラー: 指定されたフォーマットと日付文字列が一致しないか、日付が無効です。\n";
30        // 詳細なエラー情報を取得することもできます (DateTimeImmutable::getLastErrors() を参照)
31        $errors = DateTimeImmutable::getLastErrors();
32        if ($errors && !empty($errors['errors'])) {
33            echo "内部エラー情報:\n";
34            foreach ($errors['errors'] as $error) {
35                echo "- " . $error . "\n";
36            }
37        }
38    }
39    echo "\n";
40}
41
42// --- 使用例 ---
43
44// 1. 標準的な'Y-m-d H:i:s'フォーマットで日付を生成する例
45createAndDisplayImmutableDateFromSpecificFormat('Y-m-d H:i:s', '2023-10-26 14:35:00');
46
47// 2. 日本語の'Y年m月d日'フォーマットで日付を生成する例
48// 注意: このフォーマットはPHPのdate関数で直接解析できませんが、createFromFormatで指定できます。
49createAndDisplayImmutableDateFromSpecificFormat('Y年m月d日', '2023年10月26日');
50
51// 3. スラッシュ区切りの'd/m/Y'フォーマットで日付を生成する例
52createAndDisplayImmutableDateFromSpecificFormat('d/m/Y', '26/10/2023');
53
54// 4. フォーマットが日付文字列と一致しないため、失敗する例
55createAndDisplayImmutableDateFromSpecificFormat('Y-m-d', '2023/10/26');
56
57// 5. 無効な日付のため、失敗する例 (2月30日)
58createAndDisplayImmutableDateFromSpecificFormat('Y-m-d', '2023-02-30');
59
60?>

PHPのdate_create_immutable_from_format関数は、特定の日付フォーマットに沿った文字列から、変更不可能な日付時刻オブジェクトであるDateTimeImmutableを生成するために使用されます。この関数は、第1引数に日付文字列の期待される書式を示す$formatを、第2引数に解析対象の$datetime文字列を受け取ります。処理が成功すると、その内容が変更されないDateTimeImmutableオブジェクトを返します。これにより、予期せぬ日付の変更を防ぎ、安全なプログラミングを促進します。一方、$formatと$datetimeが一致しない場合や、日付が有効でない場合はfalseが返されます。

提供されたサンプルコードでは、createAndDisplayImmutableDateFromSpecificFormat関数を通じて、このdate_create_immutable_from_formatの挙動が示されています。関数は、指定されたフォーマットと日付文字列でdate_create_immutable_from_formatを呼び出し、その戻り値がDateTimeImmutableオブジェクトであるかをinstanceof演算子で厳密に確認しています。成功した場合は解析された日付情報（別フォーマットでの表示やタイムスタンプ）を出力し、失敗した場合は、フォーマットの不一致や無効な日付によるエラーメッセージを表示しています。これにより、さまざまな日付フォーマットへの対応や、エラーハンドリングの重要性を具体的に理解できます。