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

Copy
1<?php
2
3/**
4 * DatePeriod クラスの `include_end_date` プロパティの動作を実演する関数。
5 *
6 * このプロパティは、日付期間を反復処理する際に、指定された終了日を期間に含めるかどうかを制御します。
7 * プロパティ名に 'include' が含まれていますが、PHPのファイルインクルード機能
8 * (例: `include 'file.php';`) やそれに関連する 'php include エラー' とは全く関係ありません。
9 * これらは機能的に異なるものですので、混同しないように注意してください。
10 *
11 * 注: `DatePeriod->include_end_date` プロパティへの直接アクセスは PHP 8.2 で導入されました。
12 *     PHP 8.0 や 8.1 では、コンストラクタのオプション `DatePeriod::INCLUDE_END_DATE` で
13 *     挙動を制御しますが、プロパティとして直接アクセスすることはできません。
14 *     このサンプルコードは PHP 8.2 以降でプロパティへの直接アクセスを含めて動作します。
15 */
16function demonstrateDatePeriodIncludeEndDate(): void
17{
18    // 期間の開始日と終了日を定義
19    $startDate = new DateTime('2023-01-01');
20    $endDate = new DateTime('2023-01-03'); // この日付が期間に含まれるかどうかがポイント
21    $interval = new DateInterval('P1D'); // 1日ごとの間隔
22
23    echo "--- 期間の終了日を含まない場合 (デフォルト挙動) ---\n";
24    // DatePeriod::INCLUDE_END_DATE オプションを指定しない場合、終了日は含まれません。
25    $periodExcludingEnd = new DatePeriod($startDate, $interval, $endDate);
26
27    echo "  設定された期間: " . $startDate->format('Y-m-d') . " から " . $endDate->format('Y-m-d') . "\n";
28    // `include_end_date` プロパティの値を確認（bool型）
29    echo "  `include_end_date` プロパティ: " . var_export($periodExcludingEnd->include_end_date, true) . "\n";
30    echo "  生成される日付:\n";
31    foreach ($periodExcludingEnd as $date) {
32        echo "    - " . $date->format('Y-m-d') . "\n";
33    }
34    echo "  結果: 終了日 (" . $endDate->format('Y-m-d') . ") は含まれていません。\n\n";
35
36    echo "--- 期間の終了日を含む場合 (DatePeriod::INCLUDE_END_DATE オプション使用) ---\n";
37    // DatePeriod::INCLUDE_END_DATE オプションを指定すると、終了日が含まれます。
38    $periodIncludingEnd = new DatePeriod($startDate, $interval, $endDate, DatePeriod::INCLUDE_END_DATE);
39
40    echo "  設定された期間: " . $startDate->format('Y-m-d') . " から " . $endDate->format('Y-m-d') . "\n";
41    // `include_end_date` プロパティの値を確認（bool型）
42    echo "  `include_end_date` プロパティ: " . var_export($periodIncludingEnd->include_end_date, true) . "\n";
43    echo "  生成される日付:\n";
44    foreach ($periodIncludingEnd as $date) {
45        echo "    - " . $date->format('Y-m-d') . "\n";
46    }
47    echo "  結果: 終了日 (" . $endDate->format('Y-m-d') . ") は含まれています。\n\n";
48}
49
50// 関数を実行して動作を確認
51demonstrateDatePeriodIncludeEndDate();
52

PHPのDatePeriodクラスは、指定された開始日から終了日までの日付の繰り返しを扱う際に使用するクラスです。このクラスのinclude_end_dateプロパティは、日付期間を反復処理する際に、設定された「終了日」そのものを期間に含めるかどうかを制御する真偽値（bool型）のプロパティです。このプロパティには引数はなく、期間に終了日が含まれる設定の場合にtrue、含まれない場合にfalseを返します。

このプロパティはPHP 8.2以降で直接アクセスしてその値を確認できますが、それ以前のバージョンではDatePeriodコンストラクタのオプションDatePeriod::INCLUDE_END_DATEを用いて挙動を制御します。

サンプルコードでは、まずデフォルトの挙動として、期間の終了日である「2023-01-03」が日付期間の繰り返しに含まれないことを示しています。次に、DatePeriod::INCLUDE_END_DATEオプションを指定することで、同じ期間設定であっても終了日「2023-01-03」が期間に含まれるようになることを確認できます。

このinclude_end_dateプロパティ名の「include」は、PHPでファイルを読み込むためのinclude文や、それに関連する「php include エラー」とは全く異なる機能です。混同しないように注意が必要です。このプロパティは、日付期間の計算における終了日の包含設定に特化したものです。

Copy
1<?php
2
3/**
4 * このファイルは、本来であれば別のヘルパーファイル (例: `util.php`) に記述され、
5 * `include 'util.php';` のように読み込まれる関数をシミュレートしています。
6 * 単一のファイルで動作するサンプルコードとして提供するため、直接定義しています。
7 *
8 * @param string $message スクリプト終了の理由を示すメッセージ。
9 * @return void
10 */
11if (!function_exists('handle_conditional_exit')) {
12    function handle_conditional_exit(string $message): void
13    {
14        echo "--- スクリプト終了処理開始 ---" . PHP_EOL;
15        echo "理由: " . $message . PHP_EOL;
16        echo "--- スクリプト終了処理完了 ---" . PHP_EOL;
17        // 実際のアプリケーションでは、ここにログ記録やリソース解放などの処理が入ります。
18        exit(0); // スクリプトを終了 (0 は通常、正常終了を意味します)
19    }
20}
21
22/**
23 * DatePeriod を使用して指定された期間の日付を処理し、
24 * `include_end_date` プロパティの動作と、条件によるスクリプトの終了 (`exit`) を示します。
25 *
26 * @param bool $shouldIncludeEndDate 期間の終端日を含めるかどうか (DatePeriod::INCLUDE_END_DATE オプションに対応)
27 * @return void
28 */
29function demonstrateDatePeriodFeatures(bool $shouldIncludeEndDate): void
30{
31    // 開始日、間隔、終了日を定義
32    $startDate = new DateTimeImmutable('2023-01-01');
33    $interval = new DateInterval('P1D'); // 1日ごと
34    $endDate = new DateTimeImmutable('2023-01-05'); // 期間の終端日
35
36    echo "--- DatePeriod 処理の開始 (" . ($shouldIncludeEndDate ? "終端日を含む" : "終端日を含まない") . ") ---" . PHP_EOL;
37
38    // DatePeriod::INCLUDE_END_DATE オプションを設定
39    // このオプションは PHP 8.0 以降で利用可能です。
40    $options = $shouldIncludeEndDate ? DatePeriod::INCLUDE_END_DATE : 0;
41    $period = new DatePeriod($startDate, $interval, $endDate, $options);
42
43    // `include_end_date` プロパティの確認
44    // このプロパティは、コンストラクタで設定されたオプションに基づき、終端日が含まれるかを示します。
45    echo "DatePeriod->include_end_date プロパティ: "
46         . ($period->include_end_date ? "true (終端日が含まれます)" : "false (終端日は含まれません)")
47         . PHP_EOL;
48
49    echo "期間内の日付をイテレートします:" . PHP_EOL;
50    $processedDatesCount = 0;
51    foreach ($period as $date) {
52        $formattedDate = $date->format('Y-m-d');
53        echo "  - 処理中の日付: " . $formattedDate . PHP_EOL;
54        $processedDatesCount++;
55
56        // 例: 特定の日付 ('2023-01-03') に到達した場合、スクリプトを `exit` で終了します。
57        // この処理は、本来 `include` される外部関数 `handle_conditional_exit` を呼び出します。
58        if ($formattedDate === '2023-01-03') {
59            handle_conditional_exit("特定の日付 ({$formattedDate}) に到達したため、処理を中断しました。");
60            // `exit()` が実行されるため、この後に続くコードは実行されません。
61        }
62    }
63
64    echo "イテレートされた日付の合計: " . $processedDatesCount . PHP_EOL;
65    echo "--- DatePeriod 処理の終了 ---" . PHP_EOL;
66    echo PHP_EOL;
67}
68
69// 終端日を含めない場合の DatePeriod の動作を示す
70demonstrateDatePeriodFeatures(false);
71
72// 注意: 上記の `demonstrateDatePeriodFeatures(false)` の呼び出しで
73// `2023-01-03` に到達するとスクリプトが `exit` によって終了するため、
74// 以下の呼び出しは通常実行されません。
75// もし両方のケースを試したい場合は、`handle_conditional_exit` 内の `exit(0)` をコメントアウトしてください。
76// demonstrateDatePeriodFeatures(true);

このPHPサンプルコードは、日付の期間を扱うDatePeriodクラスの機能と、スクリプトの実行を強制終了するexit関数の使用方法を初心者向けに示しています。

DatePeriodクラスは、開始日、終了日、および間隔を指定して、特定の日付の繰り返しを簡単に生成するために利用されます。include_end_dateはDatePeriodクラスのプロパティで、PHP 8以降で利用可能です。これは、期間の終端日をDatePeriodのループに含めるかどうかを、DatePeriodのインスタンス作成時に設定したオプション（DatePeriod::INCLUDE_END_DATE）に基づいて真偽値（trueまたはfalse）で示します。引数はなく、戻り値はbool型です。サンプルコードでは、このプロパティの値がどのように出力されるかを確認しています。

コードの中盤では、foreachループを使ってDatePeriodが生成する各日付を処理しています。途中で特定の日付（'2023-01-03'）に到達した場合、handle_conditional_exit関数が呼び出され、その内部でexit(0)が実行されます。exit関数は、その場でスクリプトの処理を完全に停止させる役割があります。引数0は、スクリプトが正常終了したことを示す一般的なステータスコードです。handle_conditional_exitは、通常は別のファイルからinclude文で読み込まれるような、共通の終了処理をシミュレートしています。このようにして、特定の条件に応じて処理を中断し、終了する方法を理解できます。