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

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setDate の使用例
5 * DateTimeImmutable オブジェクトの日付部分を新しい値に設定し、
6 * その結果として新しい DateTimeImmutable オブジェクトを生成します。
7 */
8function exampleDateTimeImmutableSetDate(): void
9{
10    // 元となる DateTimeImmutable オブジェクトを生成 (時刻はそのまま維持されます)
11    $originalDateTime = new DateTimeImmutable('2023-10-26 15:30:00');
12    echo "元の日時: " . $originalDateTime->format('Y-m-d H:i:s') . PHP_EOL;
13
14    // setDate メソッドを呼び出し、日付部分を 2025年1月15日 に変更します。
15    // DateTimeImmutable は不変 (immutable) なため、元のオブジェクトは変更されず、
16    // 日付が変更された新しい DateTimeImmutable オブジェクトが返されます。
17    $newDateTime = $originalDateTime->setDate(2025, 1, 15);
18
19    // setDate が成功したかを確認し、結果を表示
20    if ($newDateTime === false) {
21        echo "日付の設定に失敗しました。" . PHP_EOL;
22    } else {
23        echo "日付変更後の新しい日時: " . $newDateTime->format('Y-m-d H:i:s') . PHP_EOL;
24        // 元のオブジェクトが変更されていないことを確認
25        echo "元のオブジェクトは変更されていない: " . $originalDateTime->format('Y-m-d H:i:s') . PHP_EOL;
26    }
27}
28
29// 関数を実行してサンプルコードの動作を確認
30exampleDateTimeImmutableSetDate();

PHP 8のDateTimeImmutable::setDateメソッドは、DateTimeImmutableオブジェクトの年、月、日の部分を新しい値に設定します。このメソッドの重要な特徴は、DateTimeImmutableが「不変（immutable）」であるため、元のオブジェクトを変更せず、日付が更新された新しいDateTimeImmutableオブジェクトを生成して返す点です。

引数には、整数で$year、$month、$dayを指定して日付を設定します。戻り値は、日付設定に成功した場合には新しいDateTimeImmutableオブジェクト、日付が不正などの理由で失敗した場合にはfalseです。

サンプルコードでは、2023-10-26の日付を持つオブジェクトから、setDateを使って2025-01-15という新しい日付を持つオブジェクトを生成しています。このとき、元のオブジェクトは変更されずに保持され、新しい日付情報を持つオブジェクトが別途生成されます。これにより、元のオブジェクトの参照に影響を与えることなく、安全に日付操作が行えます。

Copy
1<?php
2
3/**
4 * DateTimeImmutable::setDate メソッドの使用例を示します。
5 * このメソッドは、既存の DateTimeImmutable オブジェクトの日付部分を、
6 * 新しい年、月、日で変更し、新しい DateTimeImmutable オブジェクトを返します。
7 * 元のオブジェクトは変更されません（不変性）。
8 */
9function demonstrateSetDateExample(): void
10{
11    // 1. 現在の日付と時刻でDateTimeImmutableオブジェクトを初期化
12    //    例として2023年1月15日10時30分00秒を設定
13    $originalDate = new DateTimeImmutable('2023-01-15 10:30:00');
14    echo "元のDateTimeImmutableオブジェクト: " . $originalDate->format('Y-m-d H:i:s') . "\n";
15
16    // 2. setDateメソッドを使用して日付部分のみを変更
17    //    年: 2024, 月: 7, 日: 20 に設定します。
18    //    時刻部分は元のオブジェクトのまま維持されます。
19    $newDate = $originalDate->setDate(2024, 7, 20);
20
21    // 3. setDateは成功した場合に新しいDateTimeImmutableオブジェクトを返します。
22    //    失敗した場合はfalseを返しますが、ここでは正しい日付を指定しているため成功します。
23    if ($newDate instanceof DateTimeImmutable) {
24        echo "日付変更後のDateTimeImmutableオブジェクト: " . $newDate->format('Y-m-d H:i:s') . "\n";
25
26        // 元のオブジェクトが変更されていないことを確認します。
27        echo "元のオブジェクトは変更されていません: " . $originalDate->format('Y-m-d H:i:s') . "\n";
28    } else {
29        // 日付の設定に失敗した場合の処理（例: 不正な日付を指定した場合など）
30        echo "エラー: 日付の設定に失敗しました。\n";
31    }
32}
33
34// 関数を実行し、動作を確認します。
35demonstrateSetDateExample();
36

PHP 8で提供されるDateTimeImmutable::setDateメソッドは、DateTimeImmutableオブジェクトの日付部分のみを変更したい場合に使用します。このメソッドは、既存のDateTimeImmutableオブジェクトから、指定された新しい年、月、日で日付を再設定した新しいDateTimeImmutableオブジェクトを生成して返します。DateTimeImmutableクラスの特性である「不変性」により、このメソッドを呼び出しても元のオブジェクトが直接変更されることはありません。

引数には、変更したい日付の年を整数で指定する$year、月を整数で指定する$month、日を整数で指定する$dayを渡します。これらの引数で日付を指定すると、元のオブジェクトの時刻部分（時、分、秒）はそのまま維持されます。

メソッドの戻り値は、日付の設定に成功した場合は新しいDateTimeImmutableオブジェクトです。日付として不適切な値が指定された場合など、何らかの理由で日付の設定に失敗した場合はfalseが返されます。

サンプルコードでは、まず特定の初期日付を持つDateTimeImmutableオブジェクトを作成し、そのオブジェクトに対してsetDateメソッドを呼び出しています。これにより、新しい日付が設定された別のDateTimeImmutableオブジェクトが生成され、元のオブジェクトは変更されていないことが確認できます。