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

<?php

/**
 * 指定されたフォーマットと日付文字列からDateTimeImmutableオブジェクトを生成し、結果を表示します。
 *
 * @param string $format   日付文字列の期待されるフォーマット（例: 'Y-m-d H:i:s', 'd/m/Y'）
 * @param string $datetime 解析する日付と時刻の文字列
 * @return void
 */
function createAndDisplayImmutableDateFromSpecificFormat(string $format, string $datetime): void
{
    // date_create_immutable_from_format関数を使用して、指定されたフォーマットで
    // 日付文字列を解析し、DateTimeImmutableオブジェクトを生成します。
    // 成功した場合はDateTimeImmutableオブジェクト、失敗した場合はfalseを返します。
    $immutableDateTime = date_create_immutable_from_format($format, $datetime);

    // オブジェクトの生成が成功したかを確認します。
    // instanceof DateTimeImmutable を使用して、戻り値が正しいオブジェクト型であるかを厳密にチェックします。
    if ($immutableDateTime instanceof DateTimeImmutable) {
        echo "--- 成功: フォーマット '{$format}' から日付を生成 ---\n";
        // 生成されたDateTimeImmutableオブジェクトを別のフォーマットで表示します。
        echo "オリジナル: '{$datetime}'\n";
        echo "解析後: " . $immutableDateTime->format('Y年m月d日 H時i分s秒') . "\n";
        echo "タイムスタンプ: " . $immutableDateTime->getTimestamp() . "\n";
    } else {
        // オブジェクトの生成に失敗した場合（例: フォーマットが一致しない、無効な日付など）。
        echo "--- 失敗: フォーマット '{$format}' から日付を生成できませんでした ---\n";
        echo "指定された日付: '{$datetime}'\n";
        echo "エラー: 指定されたフォーマットと日付文字列が一致しないか、日付が無効です。\n";
        // 詳細なエラー情報を取得することもできます (DateTimeImmutable::getLastErrors() を参照)
        $errors = DateTimeImmutable::getLastErrors();
        if ($errors && !empty($errors['errors'])) {
            echo "内部エラー情報:\n";
            foreach ($errors['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
    echo "\n";
}

// --- 使用例 ---

// 1. 標準的な'Y-m-d H:i:s'フォーマットで日付を生成する例
createAndDisplayImmutableDateFromSpecificFormat('Y-m-d H:i:s', '2023-10-26 14:35:00');

// 2. 日本語の'Y年m月d日'フォーマットで日付を生成する例
// 注意: このフォーマットはPHPのdate関数で直接解析できませんが、createFromFormatで指定できます。
createAndDisplayImmutableDateFromSpecificFormat('Y年m月d日', '2023年10月26日');

// 3. スラッシュ区切りの'd/m/Y'フォーマットで日付を生成する例
createAndDisplayImmutableDateFromSpecificFormat('d/m/Y', '26/10/2023');

// 4. フォーマットが日付文字列と一致しないため、失敗する例
createAndDisplayImmutableDateFromSpecificFormat('Y-m-d', '2023/10/26');

// 5. 無効な日付のため、失敗する例 (2月30日)
createAndDisplayImmutableDateFromSpecificFormat('Y-m-d', '2023-02-30');

?>

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演算子で厳密に確認しています。成功した場合は解析された日付情報（別フォーマットでの表示やタイムスタンプ）を出力し、失敗した場合は、フォーマットの不一致や無効な日付によるエラーメッセージを表示しています。これにより、さまざまな日付フォーマットへの対応や、エラーハンドリングの重要性を具体的に理解できます。