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

Copy
1<?php
2
3/**
4 * この関数は、ISO 8601 形式の繰り返し間隔文字列から DatePeriod オブジェクトを生成し、
5 * その期間内の日付を出力する例を示します。
6 *
7 * DatePeriod::createFromISO8601String は、PHP 8 で導入された静的ファクトリメソッドで、
8 * 特定の文字列形式（ISO 8601 繰り返し間隔）を解析して DatePeriod オブジェクトを作成します。
9 * これは、DateTime::createFromFormat が日付/時刻文字列を解析するのと同様に、
10 * 繰り返し期間を定義する文字列をオブジェクトに変換する点で共通の役割を持ちます。
11 *
12 * @param string $iso8601Spec ISO 8601 形式の繰り返し間隔文字列 (例: R3/2023-10-26T10:00:00Z/P1D)
13 * @return void
14 */
15function demonstrateDatePeriodFromISO8601String(string $iso8601Spec): void
16{
17    echo "与えられたISO 8601繰り返し間隔文字列: '{$iso8601Spec}'\n";
18
19    try {
20        // DatePeriod::createFromISO8601String メソッドを使用して、
21        // 指定されたISO 8601文字列から DatePeriod オブジェクトを生成します。
22        // これは静的メソッドなので、クラス名::メソッド名 で直接呼び出します。
23        $period = DatePeriod::createFromISO8601String($iso8601Spec);
24
25        echo "生成された期間内の日付:\n";
26        // DatePeriod オブジェクトは反復可能 (Iterator インターフェースを実装) なため、
27        // foreach ループで期間内の各日付を簡単に取得できます。
28        foreach ($period as $date) {
29            // 各 $date は DateTimeImmutable オブジェクトです。
30            // format メソッドで日付と時刻の表示形式を整形できます。
31            echo "  - " . $date->format('Y-m-d H:i:s T') . "\n";
32        }
33    } catch (Throwable $e) {
34        // 不適切な形式のISO 8601文字列が与えられた場合などに例外が発生します。
35        echo "エラーが発生しました: " . $e->getMessage() . "\n";
36    }
37}
38
39// ISO 8601 繰り返し間隔文字列の例:
40// R3: 3回繰り返す
41// 2023-10-26T10:00:00Z: 開始日時 (UTC)
42// P1D: 期間 (1日)
43// これは「2023年10月26日 10:00:00 UTC から毎日、合計3回繰り返す」ことを意味します。
44$exampleSpecification = 'R3/2023-10-26T10:00:00Z/P1D';
45
46// 関数を実行し、デモンストレーションを開始します。
47demonstrateDatePeriodFromISO8601String($exampleSpecification);
48
49echo "\n--- 別の例 (週次繰り返し) ---\n";
50
51// 別の例: 2回繰り返し、開始日から1週間ごと
52// R2: 2回繰り返す
53// 2024-01-01T09:00:00: 開始日時
54// P1W: 期間 (1週間)
55$anotherExampleSpecification = 'R2/2024-01-01T09:00:00/P1W';
56demonstrateDatePeriodFromISO8601String($anotherExampleSpecification);
57
58?>

PHP 8で導入されたDatePeriod::createFromISO8601Stringメソッドは、ISO 8601形式の繰り返し間隔文字列を解析し、一連の日付を扱うDatePeriodオブジェクトを生成するための静的ファクトリメソッドです。これは、DateTime::createFromFormatが特定の日付/時刻文字列からDateTimeオブジェクトを作成するのと同様に、繰り返し期間の定義文字列をオブジェクトに変換する便利な機能です。

このメソッドは、$specification引数としてISO 8601形式の繰り返し間隔文字列（例: "R3/2023-10-26T10:00:00Z/P1D"）を受け取ります。この文字列には、繰り返し回数、開始日時、そして繰り返しの間隔が定義されています。戻り値としてDatePeriodオブジェクトが返され、このオブジェクトはforeachループを使って期間内の各日付（DateTimeImmutableオブジェクト）を簡単に取り出すことができます。

サンプルコードでは、指定されたISO 8601文字列からDatePeriodオブジェクトを生成し、その期間内の日付を一つずつ画面に出力しています。例えば、"R3/2023-10-26T10:00:00Z/P1D"という文字列は「2023年10月26日10時を起点に1日ごとに3回繰り返す」という期間を示し、コードはこの定義に基づいて3つの日付を表示します。不適切な形式の文字列が与えられた場合は、例外処理によりエラーメッセージが表示され、堅牢なプログラムを作成できます。このメソッドは、定期的なイベントやスケジュール処理の実装に非常に役立ちます。

Copy
1<?php
2
3/**
4 * ISO 8601 形式の期間文字列から日付の範囲を生成し、その日付をリストアップして表示する関数。
5 *
6 * DatePeriod::createFromISO8601String メソッドは、PHP 8 で導入された静的メソッドで、
7 * ISO 8601 形式の期間文字列（例: "R5/2023-01-01/P1D" や "2023-01-01/P3D"）を解析し、
8 * その期間内のすべての日付を含む DatePeriod オブジェクトを返します。
9 *
10 * @param string $iso8601Specification ISO 8601 形式の期間文字列。
11 *                                     例1: "2023-01-01T00:00:00Z/P3D" (開始日時と期間)
12 *                                     例2: "2023-02-01T00:00:00Z/2023-02-05T00:00:00Z" (開始日時と終了日時)
13 * @param string $label この期間の説明として表示されるラベル。
14 * @return void
15 */
16function displayDatePeriodFromISO8601(string $iso8601Specification, string $label): void
17{
18    echo "--- " . $label . " ---\n";
19    echo "指定されたISO 8601期間文字列: " . $iso8601Specification . "\n";
20
21    try {
22        // DatePeriod::createFromISO8601String メソッドを使って DatePeriod オブジェクトを生成します。
23        // このメソッドは静的メソッドなので、クラス名に直接::を付けて呼び出します。
24        $period = DatePeriod::createFromISO8601String($iso8601Specification);
25
26        echo "期間内の日付:\n";
27        // 生成された DatePeriod オブジェクトは反復可能（iterable）なので、
28        // foreach ループで期間内の各日付（DateTimeImmutable オブジェクト）を取得できます。
29        foreach ($period as $date) {
30            echo "- " . $date->format('Y-m-d H:i:s') . "\n";
31        }
32        echo "\n"; // 各例の間に改行を入れて見やすくする
33
34    } catch (ValueError $e) {
35        // ISO 8601 期間文字列のフォーマットが不正な場合、ValueError がスローされます。
36        echo "エラー: 不正なISO 8601期間文字列が指定されました。\n";
37        echo "詳細: " . $e->getMessage() . "\n\n";
38    } catch (Exception $e) {
39        // その他の予期せぬエラーを捕捉します。
40        echo "予期せぬエラーが発生しました。\n";
41        echo "詳細: " . $e->getMessage() . "\n\n";
42    }
43}
44
45// --- サンプルコードの実行 ---
46
47// 例1: 開始日時と期間 (P3D = 3日間) を指定するISO 8601文字列
48// 「2023年1月1日の0時から3日間」を表します。
49displayDatePeriodFromISO8601(
50    "2023-01-01T00:00:00Z/P3D",
51    "例1: 開始日時と期間で指定"
52);
53
54// 例2: 開始日時と終了日時を指定するISO 8601文字列
55// 「2023年2月1日の0時から2023年2月5日の0時まで」を表します。
56displayDatePeriodFromISO8601(
57    "2023-02-01T00:00:00Z/2023-02-05T00:00:00Z",
58    "例2: 開始日時と終了日時で指定"
59);
60
61// 例3: 繰り返し期間 (R3 = 3回繰り返し) と開始日時と期間を指定するISO 8601文字列
62// 「2023年3月1日から1日置きに3回」を表します。
63displayDatePeriodFromISO8601(
64    "R3/2023-03-01T00:00:00Z/P1D",
65    "例3: 繰り返し期間と開始日時と期間で指定"
66);
67
68// 例4: 不正なISO 8601文字列の例
69// この場合、ValueError が発生し、エラーハンドリングの動作を確認できます。
70displayDatePeriodFromISO8601(
71    "INVALID_ISO8601_STRING",
72    "例4: 不正なISO 8601文字列"
73);
74
75?>

このサンプルコードは、PHP 8で導入されたDatePeriod::createFromISO8601Stringメソッドを利用して、ISO 8601形式の期間文字列から日付の範囲を生成し、その内容を表示する方法を示しています。このメソッドは静的メソッドであり、クラス名に直接::を付けて呼び出します。

第一引数$specificationには、"2023-01-01T00:00:00Z/P3D"（開始日時と期間）や"2023-02-01T00:00:00Z/2023-02-05T00:00:00Z"（開始日時と終了日時）、または"R3/2023-03-01T00:00:00Z/P1D"（繰り返し回数と開始日時と期間）といったISO 8601形式の期間文字列を指定します。第二引数$optionsは省略可能で、特別な設定が不要な場合は0を指定します。このメソッドは、解析に成功すると期間内の日付を含むDatePeriodオブジェクトを返します。戻り値のDatePeriodオブジェクトは、foreachループで反復可能であり、期間内の各日付をDateTimeImmutableオブジェクトとして順番に取り出すことができます。

サンプルコードでは、様々なISO 8601形式の文字列を使ってDatePeriodオブジェクトを生成し、期間内の日付を整形して表示しています。また、不正なISO 8601文字列が指定された場合にはValueErrorがスローされるため、try-catchブロックを使って適切にエラーを処理する方法も示されており、堅牢なプログラム作成の参考になります。この機能は、特定期間の日付リスト生成や繰り返しイベントのスケジューリングなど、日付の範囲を扱う多くのシナリオで役立ちます。