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

Copy
1<?php
2
3// DatePeriod クラスの getEndDate() メソッドの使用例
4// この関数は、特定の日付期間の終了日時を取得する方法を示します。
5// システムエンジニアを目指す初心者の方へ：
6// 日付の期間を扱う際に、その期間の最終日を知りたい場合にこのメソッドが役立ちます。
7
8function demonstrateGetEndDate(): void
9{
10    // 1. 期間の開始日時を定義します。
11    // DateTimeImmutable を使用することで、オブジェクト作成後に日時が不意に変更されるのを防ぎます。
12    $startDate = new DateTimeImmutable('2023-01-01');
13
14    // 2. 期間の間隔を定義します。ここでは1ヶ月とします。
15    // DatePeriod はこの間隔を使用して期間内の日付を繰り返すことができますが、
16    // getEndDate() は期間の最終日時を返します。
17    $interval = new DateInterval('P1M'); // 'P1M' は 'Period 1 Month' を意味します（1ヶ月）
18
19    // 3. 期間の終了日時を定義します。
20    $endDate = new DateTimeImmutable('2023-05-01');
21
22    // 4. DatePeriod オブジェクトを作成します。
23    // このオブジェクトは、開始日時から終了日時までの期間を表します。
24    $period = new DatePeriod($startDate, $interval, $endDate);
25
26    // 5. getEndDate() メソッドを呼び出して、期間の終了日時を取得します。
27    // このメソッドは ?DateTimeInterface 型を返すため、DateTimeImmutable オブジェクトまたは null です。
28    // 今回は明確な終了日時を指定しているため、DateTimeImmutable が返されます。
29    $retrievedEndDate = $period->getEndDate();
30
31    // 6. 取得した終了日時を表示します。
32    if ($retrievedEndDate !== null) {
33        echo "期間の開始日時: " . $startDate->format('Y-m-d') . "\n";
34        echo "期間の終了日時 (getEndDate() で取得): " . $retrievedEndDate->format('Y-m-d') . "\n";
35    } else {
36        // DatePeriod が無限期間として設定された場合などに null を返すことがあります。
37        echo "期間の終了日時を取得できませんでした。\n";
38    }
39}
40
41// 関数を実行
42demonstrateGetEndDate();

PHPのDatePeriod::getEndDate()メソッドは、特定の日付期間の終了日時を取得するために使用されます。このメソッドはDatePeriodクラスに属し、システムエンジニアが日付の範囲を扱う際、その期間の最終日をプログラムで確認したい場合に役立ちます。

このメソッドは引数を必要としません。戻り値は?DateTimeInterface型で、これは期間の終了日時を表すDateTimeImmutableオブジェクト、または終了日時が設定されていない場合（例：無限期間）にはnullを返します。

サンプルコードでは、まずDateTimeImmutableで開始日時と終了日時、DateIntervalで期間の間隔を定義し、これらを用いてDatePeriodオブジェクトを作成しています。その後、このDatePeriodオブジェクトからgetEndDate()メソッドを呼び出すことで、設定された期間の終了日時を取得しています。取得した終了日時はformat()メソッドを使って指定の形式で表示しており、nullでないことを確認してから処理を進める安全な実装が示されています。これにより、期間の終了日時を正確かつ安全に取得・利用する方法を理解できます。

Copy
1<?php
2
3// DatePeriodクラスのgetEndDateメソッドの利用例
4// このメソッドは、DatePeriodオブジェクトで定義された期間の「終了日」を取得します。
5// システムエンジニアを目指す初心者の方にも、日付オブジェクトの基本的な操作を理解しやすいように説明します。
6
7/**
8 * ある特定の期間を定義し、その終了日をDatePeriod::getEndDate()を使って取得・表示する関数です。
9 * 日付の扱いや期間の定義方法を学ぶための基本例として役立ちます。
10 */
11function demonstrateDatePeriodGetEndDate(): void
12{
13    echo "--- 明示的な終了日時を指定してDatePeriodオブジェクトを作成する例 ---\n";
14
15    // 1. 期間の「開始日時」を定義します。
16    // DateTimeImmutableは、一度作成するとその値が変更されない（不変な）日付オブジェクトで、安全な日付操作に適しています。
17    $startDate = new DateTimeImmutable('2023-01-01');
18
19    // 2. 期間の「終了日時」を定義します。
20    $endDate = new DateTimeImmutable('2023-01-31');
21
22    // 3. 期間の「間隔（インターバル）」を定義します。
23    // DateInterval('P1D') は「1日」を意味します。
24    // 'P'はPeriod（期間）、'1'は数、'D'はDay（日）を表します。
25    $interval = new DateInterval('P1D');
26
27    // 4. DatePeriodオブジェクトを作成します。
28    // これは、開始日から終了日まで、指定された間隔で繰り返される日付のコレクション（期間）を表します。
29    $period = new DatePeriod($startDate, $interval, $endDate);
30
31    echo "  定義された期間:\n";
32    echo "    開始日: " . $startDate->format('Y-m-d') . "\n";
33    echo "    終了日 (DatePeriodコンストラクタで指定): " . $endDate->format('Y-m-d') . "\n";
34    echo "    インターバル: 1日\n\n";
35
36    // 5. getEndDate()メソッドを使用して、この期間の終了日を取得します。
37    // 戻り値は DateTimeInterface オブジェクト（日付）か、または null です。
38    // そのため、結果が null でないかを確認するチェック（if文）が重要です。
39    $retrievedEndDate = $period->getEndDate();
40
41    if ($retrievedEndDate !== null) {
42        // 終了日が正常に取得できた場合、その日付を「Y-m-d」（例: 2023-01-31）形式で表示します。
43        echo "  DatePeriod::getEndDate() で取得された終了日: " . $retrievedEndDate->format('Y-m-d') . "\n";
44    } else {
45        // PHP 8.0では、通常、期間が正しく定義されていれば null にはなりません。
46        // 特定のコンストラクタ（例: 繰り返し回数のみで終了日が明示されない）の場合、PHPのバージョンによってnullを返すことがあります。
47        echo "  DatePeriod::getEndDate() は終了日を返しませんでした。\n";
48    }
49
50    echo "\n--- 繰り返し回数を指定してDatePeriodオブジェクトを作成する例 ---\n";
51    echo "  (PHP 8.0の挙動では、この場合も計算された終了日が返されます。)\n";
52
53    $startDateRecurrence = new DateTimeImmutable('2024-01-01');
54    $intervalRecurrence = new DateInterval('P7D'); // 7日ごと
55    $recurrences = 3; // 開始日を含め、合計で4つの日付（3回繰り返し）
56
57    // 繰り返し回数でDatePeriodを定義します。
58    // この場合、明示的な終了日は指定されていませんが、getEndDate()は内部的に計算された終了日を返します。
59    $periodRecurrence = new DatePeriod($startDateRecurrence, $intervalRecurrence, $recurrences);
60
61    echo "  定義された期間 (繰り返し回数指定):\n";
62    echo "    開始日: " . $startDateRecurrence->format('Y-m-d') . "\n";
63    echo "    インターバル: 7日\n";
64    echo "    繰り返し回数: " . $recurrences . "回\n\n";
65
66    $retrievedEndDateRecurrence = $periodRecurrence->getEndDate();
67
68    if ($retrievedEndDateRecurrence !== null) {
69        echo "  DatePeriod::getEndDate() で取得された終了日 (繰り返し回数指定): " . $retrievedEndDateRecurrence->format('Y-m-d') . "\n";
70        // PHP 8.0では、'2024-01-22' が出力されます。(2024-01-01 + 3回 * 7日 = 2024-01-22)
71        // 注意: PHP 8.2.0以降では、繰り返し回数で定義されたDatePeriodの場合、getEndDate()はnullを返すように変更されています。
72    } else {
73        echo "  DatePeriod::getEndDate() は終了日を返しませんでした。\n";
74    }
75}
76
77// 上記で定義した関数を実行し、サンプルコードの動作を確認します。
78demonstrateDatePeriodGetEndDate();
79
80?>

PHPのDatePeriod::getEndDate()メソッドは、日付の期間を表すDatePeriodオブジェクトに設定された「期間の終了日」を取得するために使用されます。このメソッドは引数を必要とせず、期間の終了日時を表すDateTimeInterfaceオブジェクトを返します。ただし、終了日が明確に定義されていないなどの特定の状況ではnullを返す可能性があるため、メソッドの戻り値がnullでないか確認する処理が重要です。

サンプルコードでは、まずDateTimeImmutableオブジェクトで開始日と終了日、そしてDateIntervalで期間の間隔を定義し、これらを使ってDatePeriodオブジェクトを作成しています。その後、$period->getEndDate()を呼び出すことで、定義された期間の終了日を取得し、その日付をY-m-d形式で表示しています。

また、終了日を直接指定せず、繰り返し回数で期間を定義するDatePeriodの作成例も示しています。PHP 8.0ではこの場合でも内部的に計算された終了日が返されますが、PHP 8.2.0以降ではnullを返す可能性があることにも注意が必要です。このように、getEndDate()メソッドは日付期間の最終日を知りたい場合に役立つ機能であり、システムエンジニアを目指す方にとって日付オブジェクトの扱いを学ぶ上で基礎的な理解に繋がります。