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

Copy
1<?php
2
3/**
4 * 指定された日付文字列とフォーマットから DateTimeImmutable オブジェクトを作成します。
5 *
6 * この関数は、まず `DateTime::createFromFormat` を使用して可変な `DateTime` オブジェクトを生成し、
7 * 次に `DateTimeImmutable::createFromMutable` を使用してそれを不変な `DateTimeImmutable` オブジェクトに変換します。
8 *
9 * @param string $dateString 解析する日付文字列 (例: "2023-10-26 14:30:00")
10 * @param string $format 日付文字列のフォーマット (例: "Y-m-d H:i:s")
11 * @return DateTimeImmutable|null 成功した場合は `DateTimeImmutable` オブジェクト、失敗した場合は `null`
12 */
13function createImmutableDateTimeFromFormat(string $dateString, string $format): ?DateTimeImmutable
14{
15    // 1. 日付文字列と指定されたフォーマットから可変な DateTime オブジェクトを作成します。
16    //    `DateTime::createFromFormat` は、日付文字列の解析に失敗した場合に `false` を返します。
17    $mutableDateTime = DateTime::createFromFormat($format, $dateString);
18
19    if ($mutableDateTime === false) {
20        // 解析エラーが発生した場合、`null` を返して呼び出し元に失敗を通知します。
21        return null;
22    }
23
24    // 2. 作成された可変な DateTime オブジェクトから、不変な DateTimeImmutable オブジェクトを生成します。
25    //    `DateTimeImmutable::createFromMutable()` は、元の `DateTime` オブジェクトの状態をコピーして
26    //    新しい不変なオブジェクトを作成します。これにより、元のオブジェクトが変更されても、
27    //    この新しい `DateTimeImmutable` オブジェクトには影響がありません。
28    $immutableDateTime = DateTimeImmutable::createFromMutable($mutableDateTime);
29
30    return $immutableDateTime;
31}
32
33// --- サンプル使用例 ---
34
35// 成功するケース: 日付文字列とフォーマットが一致する場合
36$dateString1 = "2023-10-26 14:30:00";
37$format1 = "Y-m-d H:i:s";
38$result1 = createImmutableDateTimeFromFormat($dateString1, $format1);
39
40if ($result1 instanceof DateTimeImmutable) {
41    echo "成功: 日付と時刻のImmutableオブジェクトが生成されました。\n";
42    echo "元の文字列: '$dateString1' (フォーマット: '$format1')\n";
43    echo "生成されたDateTimeImmutable: " . $result1->format('Y年m月d日 H時i分s秒') . "\n";
44} else {
45    echo "エラー: 日付文字列の解析に失敗しました ('$dateString1' を '$format1' で)。\n";
46}
47
48echo "\n"; // 出力の区切り
49
50// 失敗するケース: 日付文字列のフォーマットが期待されるものと一致しない場合
51$dateString2 = "26/10/2023"; // 'YYYY-MM-DD' 形式ではない
52$format2 = "Y-m-d";          // 期待されるフォーマット
53
54$result2 = createImmutableDateTimeFromFormat($dateString2, $format2);
55
56if ($result2 instanceof DateTimeImmutable) {
57    echo "成功: 日付と時刻のImmutableオブジェクトが生成されました。\n";
58    echo "元の文字列: '$dateString2' (フォーマット: '$format2')\n";
59    echo "生成されたDateTimeImmutable: " . $result2->format('Y年m月d日 H時i分s秒') . "\n";
60} else {
61    echo "エラー: 日付文字列の解析に失敗しました ('$dateString2' を '$format2' で)。\n";
62}

PHPのDateTimeImmutable::createFromMutableメソッドは、既存の可変なDateTimeオブジェクトを、不変なDateTimeImmutableオブジェクトに変換するために使用されます。DateTimeオブジェクトは、作成後にその日付や時刻を変更できる「可変」な特性を持つ一方、DateTimeImmutableオブジェクトは、一度作成されると値が変更されない「不変」な特性を持っています。この不変性は、プログラムの異なる箇所で誤ってオブジェクトが変更されるのを防ぎ、コードの安全性を高める上で非常に有効です。

このメソッドの引数には、変換したいDateTimeオブジェクトを指定します。すると、元のDateTimeオブジェクトの状態（日付、時刻、タイムゾーンなど）が完全にコピーされた新しいDateTimeImmutableオブジェクトが戻り値として返されます。この変換により、元のDateTimeオブジェクトが後から変更されたとしても、新しく生成されたDateTimeImmutableオブジェクトは影響を受けずにその時点の値を保持し続けます。

サンプルコードでは、まずDateTime::createFromFormatを使って、指定された日付文字列とそのフォーマットから一時的に可変なDateTimeオブジェクトを作成しています。この際、日付文字列の解析に失敗するとfalseが返されるため、エラーがないかを確認する処理が含まれています。解析が成功しDateTimeオブジェクトが生成された後、それをDateTimeImmutable::createFromMutableに渡すことで、最終的に安全な不変のDateTimeImmutableオブジェクトを取得しています。これは、特定のフォーマットの日付文字列から不変な日付オブジェクトを生成する際の一般的な利用パターンです。

Copy
1<?php
2
3/**
4 * DateTimeオブジェクトをDateTimeImmutableオブジェクトに変換するサンプルコード。
5 *
6 * DateTimeImmutable::createFromMutable() メソッドは、既存のDateTimeオブジェクトを受け取り、
7 * その日付と時刻情報を持つ新しいDateTimeImmutableオブジェクトを生成します。
8 * これにより、元のDateTimeオブジェクトを変更せずに、変更不可能な日付オブジェクトを扱うことができます。
9 *
10 * @see https://www.php.net/manual/ja/datetimeimmutable.createfrommutable.php
11 */
12function convertMutableToImmutableDateTime(): void
13{
14    // 1. 変更可能なDateTimeオブジェクトを作成します。
15    // このオブジェクトは、後から日付や時刻を変更することができます。
16    $mutableDateTime = new DateTime('2023-10-27 10:30:00');
17
18    echo "--- 変換前の状態 ---\n";
19    echo "元のDateTimeオブジェクトの型: " . get_class($mutableDateTime) . "\n";
20    echo "元のDateTimeオブジェクトの値: " . $mutableDateTime->format('Y-m-d H:i:s') . "\n\n";
21
22    // 2. DateTimeImmutable::createFromMutable() を使用して、
23    // 上記のDateTimeオブジェクトからDateTimeImmutableオブジェクトを作成します。
24    // このメソッドは元のDateTimeオブジェクトを変更せず、日付情報を引き継いだ新しいImmutableオブジェクトを返します。
25    $immutableDateTime = DateTimeImmutable::createFromMutable($mutableDateTime);
26
27    echo "--- 変換後の状態 ---\n";
28    echo "変換後のDateTimeImmutableオブジェクトの型: " . get_class($immutableDateTime) . "\n";
29    echo "変換後のDateTimeImmutableオブジェクトの値: " . $immutableDateTime->format('Y-m-d H:i:s') . "\n";
30}
31
32// 関数を実行してサンプルコードの動作を確認します。
33convertMutableToImmutableDateTime();

このサンプルコードは、PHPで日付と時刻を扱う際に用いられる二つの主要なオブジェクト、DateTimeとDateTimeImmutableの間で変換を行う方法を示しています。

DateTimeオブジェクトは、一度作成した後でも日付や時刻の情報を変更できる「変更可能」（mutable）なオブジェクトです。一方、DateTimeImmutableオブジェクトは、作成後は日付や時刻の情報を一切変更できない「変更不可能」（immutable）なオブジェクトです。プログラム中で意図しない変更を防ぎたい場合にDateTimeImmutableが役立ちます。

DateTimeImmutable::createFromMutable()メソッドは、既存のDateTimeオブジェクトを「変更不可能」なDateTimeImmutableオブジェクトに安全に変換するために使用されます。このメソッドは、引数として渡されたDateTimeオブジェクトが持つ日付と時刻の情報を受け取り、その情報に基づいて新しいDateTimeImmutableオブジェクトを生成し、戻り値として返します。この際、元のDateTimeオブジェクト自体は一切変更されません。

サンプルコードではまず、特定の時刻を持つDateTimeオブジェクト $mutableDateTime を作成し、その情報が表示されます。次に、DateTimeImmutable::createFromMutable($mutableDateTime) を呼び出すことで、この変更可能なオブジェクトから新しい変更不可能なDateTimeImmutableオブジェクト $immutableDateTime が作成されます。最終的に、新しいオブジェクトの型と値が表示され、元のオブジェクトが変更されずに、日付情報が引き継がれていることが確認できます。