【PHP8.x】DatePeriod::recurrencesプロパティの使い方

Copy
1<?php
2
3/**
4 * DatePeriod::recurrences プロパティの使用例を示す関数。
5 *
6 * DatePeriod クラスは、指定された期間（例：1日ごと）で繰り返される一連の日時を生成するために使われます。
7 * recurrences プロパティは、この繰り返しが「何回」行われるかを設定または取得するために使用されます。
8 *
9 * 注意: キーワード「recursion」（再帰）は一般的に関数が自分自身を呼び出すことを指しますが、
10 * DatePeriod::recurrences プロパティは「繰り返し回数」を意味します。
11 * ここでは、DatePeriod が行う「繰り返し」の文脈でこのプロパティを解説します。
12 */
13function demonstrateDatePeriodRecurrencesProperty(): void
14{
15    // 1. 繰り返し回数を明示的に指定してDatePeriodを作成するケース
16    echo "--- 繰り返し回数を指定して DatePeriod を作成するケース ---\n";
17
18    // 現在の日時を開始点とする
19    $startDateTime = new DateTimeImmutable();
20    // 1日間の間隔を設定
21    $interval = new DateInterval('P1D'); // P1D は「1日」を意味します
22    // 繰り返しの回数を5回に設定
23    $numberOfRecurrences = 5;
24
25    echo "開始日時: " . $startDateTime->format('Y-m-d H:i:s') . "\n";
26    echo "間隔: " . $interval->format('%d日') . "\n";
27    echo "指定した繰り返し回数: " . $numberOfRecurrences . "\n\n";
28
29    // DatePeriod オブジェクトを作成
30    // ここでは (開始日時, 間隔, 繰り返し回数) の形式を使用します。
31    $periodWithRecurrences = new DatePeriod($startDateTime, $interval, $numberOfRecurrences);
32
33    echo "DatePeriod オブジェクトの recurrences プロパティの値: ";
34    // recurrences プロパティは、コンストラクタで指定された繰り返し回数 (int) を返します。
35    // PHP 8以降では、このプロパティは直接アクセス可能です。
36    var_dump($periodWithRecurrences->recurrences); // int(5) が出力されます
37
38    echo "この DatePeriod が生成する日時:\n";
39    $count = 0;
40    foreach ($periodWithRecurrences as $date) {
41        echo "  - " . $date->format('Y-m-d H:i:s') . "\n";
42        $count++;
43    }
44    echo "実際に生成された繰り返し回数: " . $count . "回\n";
45    echo str_repeat('-', 60) . "\n\n";
46
47
48    // 2. 終了日時を指定してDatePeriodを作成するケース
49    echo "--- 終了日時を指定して DatePeriod を作成するケース ---\n";
50
51    // 開始日時から3日後の日時を終了点とする
52    $endDateTime = $startDateTime->add(new DateInterval('P3D'));
53
54    echo "開始日時: " . $startDateTime->format('Y-m-d H:i:s') . "\n";
55    echo "間隔: " . $interval->format('%d日') . "\n";
56    echo "終了日時: " . $endDateTime->format('Y-m-d H:i:s') . "\n\n";
57
58    // DatePeriod オブジェクトを作成
59    // ここでは (開始日時, 間隔, 終了日時) の形式を使用します。
60    // この場合、繰り返し回数は内部で計算されますが、recurrences プロパティは null を返します。
61    $periodWithEndDate = new DatePeriod($startDateTime, $interval, $endDateTime);
62
63    echo "DatePeriod オブジェクトの recurrences プロパティの値: ";
64    // recurrences プロパティは、終了日時で定義された DatePeriod の場合、null を返します。
65    var_dump($periodWithEndDate->recurrences); // null が出力されます
66
67    echo "この DatePeriod が生成する日時:\n";
68    $count = 0;
69    foreach ($periodWithEndDate as $date) {
70        echo "  - " . $date->format('Y-m-d H:i:s') . "\n";
71        $count++;
72    }
73    echo "実際に生成された繰り返し回数: " . $count . "回\n";
74    echo str_repeat('-', 60) . "\n";
75}
76
77// 上記の関数を実行して、DatePeriod::recurrences プロパティの動作を確認します。
78demonstrateDatePeriodRecurrencesProperty();

PHP 8のDatePeriodクラスが持つrecurrencesプロパティは、一連の日時を生成する際の「繰り返し回数」を示すものです。DatePeriodクラスは、開始日時、間隔、そして繰り返し回数または終了日時を指定して、連続する日時を生成するために利用されます。

このrecurrencesプロパティは引数を持ちません。戻り値はint型、またはnullです。具体的には、DatePeriodオブジェクトを生成する際に、繰り返しの「回数」を直接指定した場合（例えば「5回繰り返す」）、recurrencesプロパティはその指定された回数をint型で返します。

一方、DatePeriodオブジェクトを生成する際に、繰り返し回数ではなく「終了日時」を指定した場合は、このプロパティはnullを返します。この場合、繰り返し回数は内部で計算されますが、プロパティとしては明示的な回数が設定されていないためnullとなるのです。

プログラミングの文脈で「recursion（再帰）」という言葉は関数が自分自身を呼び出すことを指しますが、このrecurrencesプロパティはDatePeriodが行う「繰り返し」の回数を意味し、再帰とは異なるため混同しないようご注意ください。PHP 8以降では、このプロパティに直接アクセスできるようになり、簡潔に繰り返し回数の情報を取得できるようになりました。

Copy
1<?php
2
3// DatePeriodクラスのrecurrencesプロパティの使用例
4// PHP 8以降で利用可能です。
5
6// recurrencesプロパティは、DatePeriodオブジェクトが反復する回数を整数値で返します。
7// DatePeriodのコンストラクタで繰り返し回数を明示的に指定した場合に特に有用です。
8
9// 1. 期間の開始日を定義します。
10$start = new DateTime('2023-01-01');
11
12// 2. 繰り返し間隔を定義します（例: 1日ごと）。
13//    'P1D'は「Period 1 Day（1日間の期間）」を意味します。
14$interval = new DateInterval('P1D');
15
16// 3. DatePeriodが繰り返す回数を明示的に定義します。
17$numberOfRecurrences = 5;
18
19// 4. DatePeriodオブジェクトを作成します。
20//    コンストラクタには「開始日」「間隔」「繰り返し回数」を渡します。
21//    これにより、2023-01-01から始まり、5回繰り返される期間が定義されます。
22$period = new DatePeriod($start, $interval, $numberOfRecurrences);
23
24// 5. DatePeriod::recurrencesプロパティにアクセスし、
25//    DatePeriodオブジェクトに設定された繰り返し回数を取得します。
26//    このプロパティはint型の値、または繰り返し回数が未定義の場合はnullを返します。
27$actualRecurrences = $period->recurrences;
28
29// 結果を出力して確認します。
30echo "DatePeriodオブジェクトに指定された繰り返し回数: " . $numberOfRecurrences . "回\n";
31echo "DatePeriod::recurrencesプロパティから取得した繰り返し回数: " . ($actualRecurrences ?? 'null') . "回\n";
32
33// 取得した値が期待通りであるかを確認します。
34if ($actualRecurrences === $numberOfRecurrences) {
35    echo "=> recurrencesプロパティは、指定された繰り返し回数を正しく取得しました。\n";
36} else {
37    echo "=> recurrencesプロパティの値が期待と異なります。\n";
38}
39
40?>

このPHPのサンプルコードは、PHP 8以降で導入されたDatePeriodクラスのrecurrencesプロパティの使い方を具体的に示しています。DatePeriodクラスは、開始日、繰り返し間隔、そして繰り返す回数を指定して、一定の期間を生成する際に利用されます。このrecurrencesプロパティは、そのDatePeriodオブジェクトが「何回繰り返すように設定されているか」を整数値で取得するために使用されます。

サンプルコードでは、2023年1月1日を開始日とし、1日ごとの間隔で5回繰り返すDatePeriodオブジェクトを作成しています。$period->recurrencesのようにプロパティにアクセスすることで、このオブジェクトに設定された繰り返し回数を取得できます。このプロパティは引数を取りません。戻り値は、繰り返し回数が設定されていれば整数値（int）を返し、もし繰り返し回数が明示的に指定されていない場合にはnullを返します。これにより、定義された期間の繰り返し回数をプログラムで正確に把握し、その後の処理に活かすことが可能となります。システムエンジニアを目指す方にとって、日付や期間を扱う際に、このように設定値を確認できるプロパティは、処理の信頼性向上に貢献します。