【PHP8.x】setISODateメソッドの使い方
setISODateメソッドの使い方について、初心者にもわかりやすく解説します。
基本的な使い方
『setISODateメソッドは、ISO 8601形式の年と週番号、および曜日を指定して、新しい日付を設定したDateTimeImmutableオブジェクトを生成するメソッドです。』 このメソッドは、国際規格で定められた「年の第何週の何曜日」という形式で日付を扱う際に使用します。第1引数に年、第2引数にその年の週番号を整数で指定します。第3引数は任意で、曜日を1（月曜日）から7（日曜日）までの数値で指定します。この引数を省略した場合、デフォルトで1（月曜日）が適用されます。DateTimeImmutableクラスは不変（イミュータブル）な性質を持つため、このメソッドを呼び出しても、元のオブジェクトの状態は一切変更されません。その代わりに、指定された日付が設定された新しいDateTimeImmutableオブジェクトのインスタンスが返されます。したがって、メソッドの実行結果を新しい変数に代入して利用することが不可欠です。処理が成功した場合は新しいオブジェクトを返しますが、不正な日付が指定された場合など、処理に失敗した場合はfalseを返します。
構文(syntax)
1<?php 2 3// 元となる日付オブジェクトを作成（現在の日時） 4$date = new DateTimeImmutable(); 5 6// ISO 8601形式の年・週番号・曜日を指定して、新しい日付オブジェクトを生成します。 7// 例: 2024年の第10週の3日目（水曜日） 8$newDate = $date->setISODate(2024, 10, 3); 9 10// 新しい日付オブジェクトを 'Y-m-d' 形式で出力 11echo $newDate->format('Y-m-d'); 12 13?>
引数(parameters)
int $year, int $week, int $dayOfWeek = 1
- int $year: ISO 8601 形式での年を指定する整数
- int $week: ISO 8601 形式での週番号を指定する整数 (1 から 53)
- int $dayOfWeek = 1: ISO 8601 形式での曜日を指定する整数 (1: 月曜日, 7: 日曜日)。デフォルトは月曜日 (1)
戻り値(return)
DateTimeImmutable
指定されたISO週番号と曜日に設定された新しいDateTimeImmutableオブジェクトを返します。
サンプルコード
PHP DateTimeImmutable setISODate でISO週番号を設定する
1<?php 2 3/** 4 * DateTimeImmutable::setISODate() メソッドの基本的な使用例を示す関数。 5 * 6 * このメソッドは、ISO 8601 週番号付けシステムに基づいて、 7 * 特定の年、週、曜日に日付を設定します。 8 * 9 * @param int $year 設定したい年（例: 2023） 10 * @param int $week 設定したい週番号（例: 1から53）。ISO週番号は1から始まります。 11 * ISO週番号の第1週は、その年の最初の木曜日を含む週です。 12 * @param int $dayOfWeek 設定したい曜日（1=月曜日、7=日曜日）。デフォルトは1（月曜日）。 13 * @return void 14 */ 15function demonstrateSetISODate(int $year, int $week, int $dayOfWeek = 1): void 16{ 17 echo "--- DateTimeImmutable::setISODate() の使用例 ---\n"; 18 19 // DateTimeImmutable オブジェクトを任意の初期日付と時刻で作成します。 20 // setISODate メソッドは呼び出し元のオブジェクトを変更せず、 21 // 新しい日付が設定された DateTimeImmutable オブジェクトを返します。 22 // このメソッドは日付部分のみを変更し、時刻は元のオブジェクトの時刻が保持されます。 23 $initialDate = new DateTimeImmutable('2000-01-01 15:30:00'); // 初期日付と時刻 24 echo "初期日付と時刻: " . $initialDate->format('Y-m-d H:i:s (N:l)') . "\n"; 25 26 // setISODate メソッドを呼び出し、新しい日付を持つDateTimeImmutableオブジェクトを受け取ります。 27 $newDate = $initialDate->setISODate($year, $week, $dayOfWeek); 28 29 echo "設定内容:\n"; 30 echo " 年: {$year}, 週: {$week}, 曜日 (1=月, 7=日): {$dayOfWeek}\n"; 31 echo "結果日付と時刻: " . $newDate->format('Y-m-d H:i:s (N:l)') . "\n\n"; 32 33 // initialDate オブジェクトは変更されずに元の状態を保ちます。 34 // そのため、setISODate の結果は必ず新しい変数に代入して使用します。 35} 36 37// 例1: 2023年の第1週の月曜日を設定 (曜日を省略、デフォルトの月曜日) 38// 2023年1月1日は日曜日ですが、ISO週番号の第1週は1月2日(月)から始まります。 39demonstrateSetISODate(2023, 1); 40 41// 例2: 2024年の第10週の金曜日を設定 (曜日を明示的に指定) 42demonstrateSetISODate(2024, 10, 5); // 5は金曜日 43 44// 例3: 2025年の第52週の日曜日を設定 45demonstrateSetISODate(2025, 52, 7); // 7は日曜日
DateTimeImmutable::setISODate()メソッドは、日付と時刻を扱うDateTimeImmutableクラスの機能で、ISO 8601という国際的な週番号付けの基準に基づいて特定の日付を設定します。指定された年、週番号、そして曜日に基づいて日付を計算し、設定することが可能です。
引数としては、日付を設定したい年を示す$year、1から53の範囲で指定するISO週番号の$week、そして1（月曜日）から7（日曜日）で指定する曜日の$dayOfWeekを受け取ります。$dayOfWeekは省略可能で、その場合のデフォルト値は1（月曜日）です。ISO週番号の第1週は、その年の最初の木曜日が含まれる週として定義されます。
このメソッドはDateTimeImmutableクラスの特性により、呼び出し元のオブジェクト自身は変更しません。代わりに、新しい日付が設定されたDateTimeImmutableの新しいオブジェクトを返します。そのため、メソッドの実行結果は必ず新しい変数に代入して使用する必要があります。日付部分のみが更新され、時刻は元のオブジェクトのものが保持されます。特定の日付を週番号から計算したい場合に非常に便利な機能です。
DateTimeImmutable::setISODate()メソッドは、元のオブジェクトを変更せず、日付が更新された新しいDateTimeImmutableオブジェクトを返します。そのため、メソッドの戻り値を必ず新しい変数で受け取って使用してください。元のオブジェクトの時刻は保持されたまま、日付のみがISO 8601週番号付けシステムに基づいて設定されます。ISO週番号の第1週はその年の最初の木曜日を含む週であり、曜日は1が月曜日、7が日曜日を示します。引数を省略した場合、曜日はデフォルトで月曜日が設定されますのでご注意ください。