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

Copy
1<?php
2
3/**
4 * Demonstrates the use of DateTime::setISODate method in PHP.
5 *
6 * This function illustrates how to set a DateTime object's date
7 * based on the ISO 8601 week date system. In this system, a year is
8 * defined by its week number and day of the week (Monday=1 to Sunday=7).
9 * This is particularly useful for calendar and scheduling systems
10 * that adhere to ISO week standards.
11 */
12function demonstrateDateTimeSetISODate(): void
13{
14    // 1. Initialize a new DateTime object.
15    // It defaults to the current date and time.
16    $dateTime = new DateTime();
17    echo "Initial date: " . $dateTime->format('Y-m-d (N: Monday=1) W:ISO Week') . PHP_EOL;
18
19    // 2. Set the date to a specific ISO year and week, using the default dayOfWeek (Monday).
20    $isoYear = 2023;
21    $isoWeek = 35; // For example, the 35th week of 2023
22    echo PHP_EOL . "--- Setting date to ISO year {$isoYear}, week {$isoWeek}, default day (Monday) ---" . PHP_EOL;
23
24    // The setISODate method returns the DateTime object on success, or false on failure.
25    $result = $dateTime->setISODate($isoYear, $isoWeek);
26
27    if ($result !== false) {
28        echo "Date after setISODate (Monday): " . $dateTime->format('Y-m-d (N: Monday=1) W:ISO Week') . PHP_EOL;
29        echo "Note: The 'N' value is 1, indicating Monday." . PHP_EOL;
30    } else {
31        echo "Error: Failed to set ISO date for year {$isoYear}, week {$isoWeek}." . PHP_EOL;
32    }
33
34    // 3. Set the date to the same ISO year and week, but a different day of the week (e.g., Friday).
35    $dayOfWeek = 5; // 5 represents Friday in ISO 8601 (1=Monday, 7=Sunday)
36    echo PHP_EOL . "--- Setting date to ISO year {$isoYear}, week {$isoWeek}, day {$dayOfWeek} (Friday) ---" . PHP_EOL;
37
38    $result = $dateTime->setISODate($isoYear, $isoWeek, $dayOfWeek);
39
40    if ($result !== false) {
41        echo "Date after setISODate (Friday): " . $dateTime->format('Y-m-d (N: Monday=1) W:ISO Week') . PHP_EOL;
42        echo "Note: The 'N' value is 5, indicating Friday." . PHP_EOL;
43    } else {
44        echo "Error: Failed to set ISO date for year {$isoYear}, week {$isoWeek}, day {$dayOfWeek}." . PHP_EOL;
45    }
46
47    // 4. Example with the last week of an ISO year to show year boundary handling.
48    // For 2023, the last ISO week is week 52.
49    $isoYearEndOfYear = 2023;
50    $isoWeekEndOfYear = 52;
51    $dayOfWeekEndOfYear = 7; // Sunday
52    echo PHP_EOL . "--- Setting date to ISO year {$isoYearEndOfYear}, week {$isoWeekEndOfYear}, day {$dayOfWeekEndOfYear} (Sunday) ---" . PHP_EOL;
53
54    $result = $dateTime->setISODate($isoYearEndOfYear, $isoWeekEndOfYear, $dayOfWeekEndOfYear);
55
56    if ($result !== false) {
57        echo "Date after setISODate (end of year Sunday): " . $dateTime->format('Y-m-d (N: Monday=1) W:ISO Week') . PHP_EOL;
58        echo "Observe how the actual month/day might fall into the next calendar year." . PHP_EOL;
59    } else {
60        echo "Error: Failed to set ISO date for year {$isoYearEndOfYear}, week {$isoWeekEndOfYear}, day {$dayOfWeekEndOfYear}." . PHP_EOL;
61    }
62}
63
64// Execute the demonstration.
65demonstrateDateTimeSetISODate();
66

PHP 8のDateTimeクラスに属するsetISODateメソッドは、日付をISO 8601週日付システムに基づいて設定する際に使用されます。このシステムでは、年、週番号、および週の曜日（月曜日を1とし、日曜日を7とする）を用いて特定の日付を表現します。

このメソッドは、DateTimeオブジェクトのインスタンスに対して呼び出され、引数としてint $yearで年を、int $weekでその年の週番号を、そしてオプションでint $dayOfWeekで週の曜日（デフォルトは1で月曜日）を指定します。従来の「年・月・日」といった形式ではなく、週単位での日付設定が可能になるため、ISO週番号を基準とするカレンダーやスケジュール管理システムにおいて特に有用です。

メソッドが日付の設定に成功した場合、更新されたDateTimeオブジェクト自身を返します。設定に失敗した場合はfalseを返しますので、戻り値を確認してエラー処理を行うことが重要です。サンプルコードでは、まずDateTimeオブジェクトを初期化し、その後、2023年の第35週の月曜日（デフォルト）と金曜日（dayOfWeekに5を指定）を設定する例を通じて、日付がISO週番号に基づいて正確に設定される様子を示しています。また、年末の週を設定する例から、実際の月日が次の暦年にまたがることがあるといった、ISO週の計算規則に厳密に従って日付が決定される挙動も確認できます。