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

Copy
1<?php
2
3/**
4 * DateTimeImmutable オブジェクトの配列を反復処理し、
5 * 各日付を指定された修飾子で変更した新しい DateTimeImmutable オブジェクトの配列を生成します。
6 *
7 * DateTimeImmutable オブジェクトは「不変 (immutable)」です。
8 * そのため、modify() メソッドを呼び出しても元のオブジェクトは変更されず、
9 * 新しい DateTimeImmutable インスタンスが返されます。
10 * この関数では、その新しいインスタンスを結果の配列に追加します。
11 *
12 * @param DateTimeImmutable[] $dates DateTimeImmutable オブジェクトの配列
13 * @param string $modifier modify() メソッドに渡す修飾文字列 (例: '+1 day', '-2 hours')
14 * @return DateTimeImmutable[] 変更された DateTimeImmutable オブジェクトの新しい配列
15 */
16function modifyDatesInArray(array $dates, string $modifier): array
17{
18    $modifiedDates = [];
19    foreach ($dates as $date) {
20        // DateTimeImmutable::modify は新しい DateTimeImmutable インスタンスを返す
21        // 元の $date オブジェクトは変更されません
22        $modifiedDates[] = $date->modify($modifier);
23    }
24    return $modifiedDates;
25}
26
27// --- サンプルコードの実行 ---
28
29// 1. 元になる DateTimeImmutable オブジェクトの配列を作成
30$initialDates = [
31    new DateTimeImmutable('2023-01-01 10:00:00'),
32    new DateTimeImmutable('2023-02-15 14:30:00'),
33    new DateTimeImmutable('2023-03-30 08:00:00'),
34];
35
36echo "--- 元の日付 ---\n";
37foreach ($initialDates as $date) {
38    echo $date->format('Y-m-d H:i:s') . "\n";
39}
40
41// 2. modifyDatesInArray 関数を呼び出し、各日付を「+1週間」変更
42$modifier = '+1 week';
43$oneWeekLaterDates = modifyDatesInArray($initialDates, $modifier);
44
45echo "\n--- 1週間後の日付 ---\n";
46foreach ($oneWeekLaterDates as $date) {
47    echo $date->format('Y-m-d H:i:s') . "\n";
48}
49
50// 3. 元の配列が変更されていないことを確認 (DateTimeImmutable の不変性の確認)
51echo "\n--- 元の日付 (再確認 - 変更されていない) ---\n";
52foreach ($initialDates as $date) {
53    echo $date->format('Y-m-d H:i:s') . "\n";
54}
55
56// 別の変更も試す: 各日付を「-2時間」変更
57$anotherModifier = '-2 hours';
58$twoHoursBeforeDates = modifyDatesInArray($initialDates, $anotherModifier);
59
60echo "\n--- 2時間前の日付 ---\n";
61foreach ($twoHoursBeforeDates as $date) {
62    echo $date->format('Y-m-d H:i:s') . "\n";
63}

PHPのDateTimeImmutableクラスは、日付と時刻を扱うオブジェクトで、その名の通り「不変（immutable）」な特性を持っています。一度作成されたオブジェクトは、その内容が変更されることはありません。modifyメソッドは、このDateTimeImmutableオブジェクトの日付や時刻を変更する際に使用し、引数$modifierに'+1 day'や'-2 hours'のような変更内容を示す文字列を指定します。このメソッドを呼び出すと、元のオブジェクトを変更するのではなく、指定された変更が適用された「新しいDateTimeImmutableオブジェクト」が戻り値として返されます。

サンプルコードでは、DateTimeImmutableオブジェクトの配列をforeachループで反復処理しています。ループ内で各日付オブジェクトに対してmodifyメソッドを呼び出すことで、元の日付から指定期間だけ変更された「新しい日付オブジェクト」が生成されます。この新しいオブジェクトを別の配列に収集することで、元の配列に影響を与えることなく、変更後の結果をまとめた新しい配列を得ています。コードの実行結果でも確認できる通り、modifyメソッドを呼び出した後も、元の$initialDates配列の内容は変更されずに保持されており、これがDateTimeImmutableクラスの不変性の重要なポイントです。

Copy
1<?php
2
3// DateTimeImmutableクラスは、一度作成されると値が変更されない（不変な）日付と時刻のオブジェクトを扱います。
4// modify()メソッドを呼び出すと、元のオブジェクトを変更するのではなく、
5// 変更が適用された新しいDateTimeImmutableオブジェクトが返されます。
6
7// 1. 現在の日付と時刻でDateTimeImmutableオブジェクトを生成します。
8$currentDate = new DateTimeImmutable();
9echo "現在の日付: " . $currentDate->format('Y-m-d') . "\n";
10
11// 2. modify()メソッドを使って1ヶ月後の日付を取得します。
12// 引数 '+1 month' は、現在の月に1ヶ月加算することを指示します。
13$oneMonthLater = $currentDate->modify('+1 month');
14echo "1ヶ月後の日付: " . $oneMonthLater->format('Y-m-d') . "\n";
15
16// 3. modify()メソッドを使って2ヶ月前の日付を取得します。
17// 引数 '-2 months' は、現在の月から2ヶ月減算することを指示します。
18$twoMonthsAgo = $currentDate->modify('-2 months');
19echo "2ヶ月前の日付: " . $twoMonthsAgo->format('Y-m-d') . "\n";
20
21// 4. modify()メソッドを使って次の月の最初の日を取得します。
22// 引数 'first day of next month' は、文字通り「次の月の最初の日」を意味します。
23$firstDayOfNextMonth = $currentDate->modify('first day of next month');
24echo "次の月の最初の日: " . $firstDayOfNextMonth->format('Y-m-d') . "\n";
25
26?>

DateTimeImmutable::modify()メソッドは、PHPで日付や時刻を扱うDateTimeImmutableクラスのオブジェクトに対し、指定したルールに基づいて日付や時刻を変更するための機能です。

DateTimeImmutableクラスのオブジェクトは、一度作成されると値が変更されない「不変（immutable）」な特性を持っています。そのため、modify()メソッドを呼び出すと、元のオブジェクト自体を変更するのではなく、変更が適用された新しいDateTimeImmutableオブジェクトを生成し、それを戻り値として返します。元のオブジェクトは影響を受けずにそのまま残ります。

引数$modifierには、日付や時刻の変更内容を指示する文字列を渡します。例えば、「+1 month」と指定すれば1ヶ月後の日付、「-2 months」と指定すれば2ヶ月前の日付を計算できます。また、「first day of next month」のように、より複雑で具体的な日付の指定も可能です。

このメソッドを利用することで、現在の日付から将来や過去の特定の日付を簡単に取得したり、「次の月の最初の日」といった条件での日付計算を直感的な文字列で記述し、新しいDateTimeImmutableオブジェクトとして取得できます。これにより、日付に関する処理を簡潔かつ安全に行うことが可能になります。