Oihana PHP Standards

Iso8601Recurrence

Represents and manipulates ISO 8601 recurring intervals.

The format is R[n]/<interval> where n is an optional non-negative integer count (absent means infinite) and <interval> is any bounded Iso8601Interval form.

Example usage:

use org\iso\Iso8601Recurrence;

// Five daily occurrences starting 2026-05-14
$r = new Iso8601Recurrence('R5/2026-05-14T00:00:00Z/P1D');
echo $r->count;                          // 5
echo $r->interval->start->iso;           // "2026-05-14T00:00:00Z"

foreach ($r->occurrences() as $instant) {
    echo $instant->format('Y-m-d') . PHP_EOL ;
    // 2026-05-14, 2026-05-15, 2026-05-16, 2026-05-17, 2026-05-18
}

// Infinite recurrence — max is required
$r = new Iso8601Recurrence('R/2026-05-14T00:00:00Z/P1D');
foreach ($r->occurrences(max: 3) as $instant) { ... }
Tags
link

ISO 8601 Repeating intervals
author

Marc Alcaraz (ekameleon)

since
1.0.2

Table of Contents

Constants

DESIGNATOR  : string = 'R'
Recurrence designator (required prefix).
PATTERN  : string = '/^R(\d*)\/(.+)$/'
ISO recurrence pattern: `R[n]/<interval>`.
ZERO  : string = 'R0/1970-01-01T00:00:00Z/PT0S'
Zero recurrence constant: zero occurrences of a zero-length interval at the Unix epoch.

Properties

$count  : int|null
Number of repetitions. `null` means infinite.
$interval  : Iso8601Interval
The underlying bounded interval.
$iso  : string
ISO string representation. Round-trip preserves the input form.
$_count  : int|null
$_interval  : Iso8601Interval
$_iso  : string

Methods

__construct()  : mixed
Creates a new Iso8601Recurrence instance.
__toString()  : string
String cast returns the ISO representation.
occurrences()  : Generator<int, DateTimeImmutable>
Yields the start instant of each occurrence as a {@see DateTimeImmutable}.
period()  : DateInterval
Returns the period between successive occurrences, using the interval's declared duration when available, otherwise the diff between end and start.

Constants

DESIGNATOR

Recurrence designator (required prefix).

public string DESIGNATOR = 'R'

PATTERN

ISO recurrence pattern: `R[n]/<interval>`.

public string PATTERN = '/^R(\d*)\/(.+)$/'

Group 1 captures the (possibly empty) count; group 2 captures the inner interval.

ZERO

Zero recurrence constant: zero occurrences of a zero-length interval at the Unix epoch.

public string ZERO = 'R0/1970-01-01T00:00:00Z/PT0S'

Properties

$count read-only virtual

Number of repetitions. `null` means infinite.

public int|null $count
Hooks
public int|null get

$iso virtual

ISO string representation. Round-trip preserves the input form.

public string $iso
Tags
throws
InvalidArgumentException

If the value is not a valid recurrence

Hooks
public string get public set

Methods

__construct()

Creates a new Iso8601Recurrence instance.

public __construct([string|null $iso = null ]) : mixed
Parameters
$iso : string|null = null

ISO 8601 recurrence string, or null for the zero recurrence (ZERO)

Tags
throws
InvalidArgumentException

If the input is not a valid recurrence

__toString()

String cast returns the ISO representation.

public __toString() : string
Return values
string

occurrences()

Yields the start instant of each occurrence as a {@see DateTimeImmutable}.

public occurrences([int|null $max = null ]) : Generator<int, DateTimeImmutable>

If the recurrence has a finite count, at most count occurrences are yielded; when both count and $max are provided, the smaller of the two wins. If count is null (infinite), $max is mandatory to avoid unbounded iteration.

Parameters
$max : int|null = null

Optional cap on the number of yielded occurrences. Required when count is null.

Tags
throws
LogicException

If the recurrence is infinite and $max is not provided.

Return values
Generator<int, DateTimeImmutable>

period()

Returns the period between successive occurrences, using the interval's declared duration when available, otherwise the diff between end and start.

private period() : DateInterval
Return values
DateInterval
On this page

Search results