【PHP8.x】createFromFormatメソッドの使い方

Copy
1<?php
2
3declare(strict_types=1);
4
5/**
6 * DateTimeImmutable::createFromFormat の使用例
7 *
8 * この関数は、指定されたフォーマットの文字列から
9 * 変更不可能な(Immutable)日付時刻オブジェクトを生成する方法を示します。
10 */
11function createDateTimeExample(): void
12{
13    // --- 基本的な使用例 ---
14    // 'Y-m-d H:i:s' というフォーマットを指定し、対応する文字列からオブジェクトを生成します。
15    $format = 'Y-m-d H:i:s';
16    $dateString = '2023-10-27 10:30:00';
17
18    $dateTime = DateTimeImmutable::createFromFormat($format, $dateString);
19
20    // 生成に成功した場合、DateTimeImmutableオブジェクトが返されます。
21    if ($dateTime instanceof DateTimeImmutable) {
22        // format()メソッドを使って、別の形式で日付を出力します。
23        echo '生成された日時: ' . $dateTime->format('Y年m月d日 H時i分') . PHP_EOL;
24    } else {
25        echo '日時の生成に失敗しました。' . PHP_EOL;
26    }
27
28
29    // --- タイムゾーンを指定する例 ---
30    // 第3引数にDateTimeZoneオブジェクトを渡すことで、タイムゾーンを指定できます。
31    $dateStringWithTz = '2024-01-01 00:00:00';
32    $timezone = new DateTimeZone('Asia/Tokyo');
33
34    $dateTimeInTokyo = DateTimeImmutable::createFromFormat($format, $dateStringWithTz, $timezone);
35
36    if ($dateTimeInTokyo instanceof DateTimeImmutable) {
37        // ATOM形式 (例: 2024-01-01T00:00:00+09:00) で出力し、タイムゾーンを確認します。
38        echo '東京のタイムゾーンでの日時: ' . $dateTimeInTokyo->format(DateTime::ATOM) . PHP_EOL;
39    }
40
41
42    // --- 失敗する例 ---
43    // 指定したフォーマットと文字列が一致しない場合、このメソッドは false を返します。
44    $invalidDateString = '2023/10/27 10-30-00'; // フォーマットと区切り文字が違う
45    $result = DateTimeImmutable::createFromFormat($format, $invalidDateString);
46
47    if ($result === false) {
48        echo 'フォーマットが不一致のため、日時の生成に失敗しました。' . PHP_EOL;
49    }
50}
51
52// 関数を実行して結果を表示
53createDateTimeExample();

PHPのDateTimeImmutable::createFromFormatメソッドは、指定した書式の文字列から、後から値を変更できないDateTimeImmutableオブジェクトを生成する静的メソッドです。

第1引数$formatに、'Y-m-d H:i:s'のような日付の書式を指定し、第2引数$datetimeにはその書式に合った日付文字列を渡します。オプションの第3引数$timezoneを使うと、特定のタイムゾーンを持つオブジェクトを生成できます。

このメソッドは、日付文字列の解析に成功するとDateTimeImmutableオブジェクトを返します。サンプルコードでは、生成したオブジェクトが持つformat()メソッドを利用して、別の書式で日時を出力しています。また、東京のタイムゾーンを指定してオブジェクトを生成する例も示しています。

もし第1引数の書式と第2引数の文字列が一致しないなど、解析に失敗した場合はfalseを返します。そのため、戻り値がfalseかどうかを確認することで、処理が成功したかを判断するのが一般的です。サンプルコードの失敗例では、フォーマットと文字列の区切り文字が異なるため、オブジェクトの生成に失敗しfalseが返されています。

Copy
1<?php
2
3/**
4 * PHPのDateTimeImmutable::createFromFormat メソッドの使用例。
5 * 指定されたフォーマットとタイムゾーンに基づいて、日付時刻文字列から
6 * 変更不可能な(Immutable)日付時刻オブジェクトを生成します。
7 *
8 * @see https://www.php.net/manual/ja/datetimeimmutable.createfromformat.php
9 */
10
11// 1. 日付時刻文字列のフォーマットを定義します。
12//    'Y' (年)、'm' (月)、'd' (日)、'H' (時・24時間形式)、'i' (分)、's' (秒)
13$format = 'Y-m-d H:i:s';
14
15// 2. 上記のフォーマットに正確に一致する日付時刻文字列を定義します。
16$datetimeString = '2023-10-27 15:30:00';
17
18// 3. タイムゾーンを定義します。
19//    'America/New_York' はニューヨークのタイムゾーン識別子です。
20$timezoneIdentifier = 'America/New_York';
21$timezone = new DateTimeZone($timezoneIdentifier);
22
23// 4. DateTimeImmutable::createFromFormat を使用してオブジェクトを生成します。
24//    引数: string $format, string $datetime, ?DateTimeZone $timezone = null
25//    戻り値: DateTimeImmutable|false (成功時はオブジェクト、失敗時は false)
26$dateTimeImmutable = DateTimeImmutable::createFromFormat(
27    $format,
28    $datetimeString,
29    $timezone
30);
31
32// 5. オブジェクトの生成が成功したかを確認し、結果を表示します。
33if ($dateTimeImmutable === false) {
34    echo "エラー: 日付時刻の解析に失敗しました。\n";
35    echo "指定したフォーマット ('" . $format . "') と日付時刻文字列 ('" . $datetimeString . "') が一致しているか確認してください。\n";
36    // より詳細なエラー情報は DateTime::getLastErrors() で取得できます。
37} else {
38    echo "--- DateTimeImmutable::createFromFormat とタイムゾーンの例 ---\n";
39    echo "元の文字列: " . $datetimeString . "\n";
40    echo "使用したフォーマット: " . $format . "\n";
41    echo "指定したタイムゾーン: " . $timezoneIdentifier . "\n";
42    
43    // 生成された DateTimeImmutable オブジェクトの情報を表示します。
44    // 'P' はタイムゾーンのオフセット (例: -04:00)、'e' はタイムゾーンの識別子 (例: America/New_York)
45    echo "生成されたDateTimeImmutableオブジェクト: " . $dateTimeImmutable->format('Y-m-d H:i:s P (e)') . "\n";
46
47    // DateTimeImmutable は変更不可能なオブジェクトであるため、
48    // setTimezone() などのメソッドを呼び出すと、新しい DateTimeImmutable オブジェクトが返されます。
49    $tokyoDateTime = $dateTimeImmutable->setTimezone(new DateTimeZone('Asia/Tokyo'));
50    echo "アジア/東京での表示 (新しいオブジェクト): " . $tokyoDateTime->format('Y-m-d H:i:s P (e)') . "\n";
51    echo "元のDateTimeImmutableオブジェクト (変更なし): " . $dateTimeImmutable->format('Y-m-d H:i:s P (e)') . "\n";
52}
53
54?>

PHP 8のDateTimeImmutable::createFromFormatメソッドは、指定された書式（フォーマット）と日付時刻文字列から、変更不可能な日付時刻オブジェクト（DateTimeImmutable）を生成するクラスメソッドです。このメソッドは、さまざまな形式の日付文字列を正確に解析したい場合に特に有用です。

第一引数には日付時刻文字列の書式を定義する$formatを、第二引数には解析したい$datetime文字列を指定します。第三引数の$timezoneには、オプションでDateTimeZoneオブジェクトを渡すことで、日付時刻がどのタイムゾーンに属するかを明確に指定できます。この$timezoneが指定されない場合、PHPのデフォルトタイムゾーンが使用されます。

サンプルコードでは、'Y-m-d H:i:s'という書式と'2023-10-27 15:30:00'という日付時刻文字列を定義し、さらに'America/New_York'のタイムゾーンを指定してオブジェクトを生成しています。メソッドが成功するとDateTimeImmutableオブジェクトが返され、失敗した場合はfalseが返されるため、必ずその結果を確認することが重要です。

生成されたオブジェクトは指定したタイムゾーンを保持し、その時刻を正確に表します。DateTimeImmutableは一度作成されると内容が変更できない特性（不変性）を持つため、時刻を変更するような操作を行うと、元のオブジェクトは変わらず、新しいDateTimeImmutableオブジェクトが返されます。これにより、意図しないデータ変更を防ぎ、より安全な日付時刻処理を実現できます。