Oihana PHP Standards

Iso8601Interval

Represents and manipulates ISO 8601 time intervals.

An interval is two ISO 8601 expressions joined by a / separator. Three bounded forms are supported:

  • <start>/<end> — two strict date-times
  • <start>/<duration> — a start date-time and a duration
  • <duration>/<end> — a duration and an end date-time

The single-<duration> short form is intentionally rejected (use Iso8601Duration for that). Open intervals (--/<end> and <start>/--) are not supported in this release.

start and end are always available as Iso8601DateTime objects. When the input form omits one of them, it is computed from the duration. The duration property reflects the input: it is null when the input form was <start>/<end>. The iso round-trip preserves the original form.

Example usage:

use org\iso\Iso8601Interval;

$i = new Iso8601Interval('2026-05-14T00:00:00Z/P1D');
echo $i->start->iso;             // "2026-05-14T00:00:00Z"
echo $i->end->iso;               // "2026-05-15T00:00:00Z" (computed)
echo $i->duration->iso;          // "P1D"
echo $i->iso;                    // "2026-05-14T00:00:00Z/P1D" (form preserved)

$i->contains(new DateTimeImmutable('2026-05-14T12:00:00Z')); // true

$other = new Iso8601Interval('2026-05-14T18:00:00Z/2026-05-16T00:00:00Z');
$i->overlaps($other);                                         // true
Tags
link

ISO 8601 Time intervals
author

Marc Alcaraz (ekameleon)

since
1.0.2

Table of Contents

Constants

SEPARATOR  : string = '/'
Interval separator.
ZERO  : string = '1970-01-01T00:00:00Z/PT0S'
Zero interval constant: a zero-duration interval anchored at the Unix epoch.

Properties

$duration  : Iso8601Duration|null
Duration of the interval as written in the input.
$end  : Iso8601DateTime
End of the interval (always available, computed if needed).
$iso  : string
ISO string representation. Round-trip preserves the input form.
$start  : Iso8601DateTime
Start of the interval (always available, computed if needed).
$_duration  : Iso8601Duration|null
$_end  : Iso8601DateTime
$_iso  : string
$_start  : Iso8601DateTime

Methods

__construct()  : mixed
Creates a new Iso8601Interval instance.
__toString()  : string
String cast returns the ISO representation.
contains()  : bool
Tests whether the given instant lies within the interval.
overlaps()  : bool
Tests whether this interval overlaps another.

Constants

ZERO

Zero interval constant: a zero-duration interval anchored at the Unix epoch.

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

Properties

$iso virtual

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

public string $iso
Tags
throws
InvalidArgumentException

If the value is not a valid interval

Hooks
public string get public set

Methods

__construct()

Creates a new Iso8601Interval instance.

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

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

Tags
throws
InvalidArgumentException

If the input is not a valid bounded interval

__toString()

String cast returns the ISO representation.

public __toString() : string
Return values
string

contains()

Tests whether the given instant lies within the interval.

public contains(DateTimeInterface|Iso8601DateTime $instant) : bool

The interval is treated as half-open: [start, end). The start instant is included, the end instant is excluded.

Parameters
$instant : DateTimeInterface|Iso8601DateTime
Return values
bool

overlaps()

Tests whether this interval overlaps another.

public overlaps(self $other) : bool

Two half-open intervals [a1, a2) and [b1, b2) overlap iff a1 < b2 && b1 < a2. Adjacent intervals (one ending where the other begins) do not overlap.

Parameters
$other : self
Return values
bool
On this page

Search results