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

date_create_immutable_from_format関数は、指定された書式（フォーマット）に基づいて日付や時刻を表す文字列を解析し、新しい不変の（Immutableな）日時オブジェクトを生成する関数です。この関数は、第一引数で'Y-m-d H:i:s'のような書式を指定し、第二引数にその書式に合致した'2024-01-01 12:30:00'のような文字列を渡して使用します。生成されるオブジェクトはDateTimeImmutableクラスのインスタンスであり、「不変」という特性を持ちます。これは、一度作成されたオブジェクトの日時情報を後から変更できないことを意味します。例えば、日付を1日進めるような操作を行った場合でも、元のオブジェクトは変更されず、変更が適用された新しいオブジェクトが返されます。この特性により、意図しない値の書き換えを防ぐことができ、プログラムの安全性を高める上で非常に有効です。また、第三引数にタイムゾーンオブジェクトを渡すことで、特定のタイムゾーンを持った日時オブジェクトとして生成することも可能です。この引数を省略した場合は、PHPの環境設定で定められたデフォルトのタイムゾーンが使用されます。解析に成功した場合はDateTimeImmutableオブジェクトを返しますが、指定された書式と文字列が一致しないなど、解析に失敗した場合はfalseを返します。

<?php
$format = 'Y-m-d H:i:s';
$datetimeString = '2023-10-26 10:30:00';
$immutableDateTime = date_create_immutable_from_format($format, $datetimeString);
?>

string $format, string $datetime, ?DateTimeZone $timezone = null

• string $format: 日付と時刻の書式を指定する文字列
• string $datetime: 指定した書式 ($format) に従った日付と時刻を表す文字列
• ?DateTimeZone $timezone = null: $datetime で指定されたタイムゾーン。省略された場合は、PHP のデフォルトタイムゾーンが使用されます。

DateTimeImmutable|false

指定されたフォーマットから、DateTimeImmutable オブジェクト、またはフォーマットエラーの場合は false を返します。