Oihana PHP Standards

Iso8601DateTime

Represents and manipulates ISO 8601 date-time strings (combined date + time).

Wraps a PHP DateTimeImmutable and keeps the ISO 8601 string representation synchronized with both the internal date-time object and a configurable output precision.

Only the strict ISO 8601 form is accepted in the iso setter: the date must be YYYY-MM-DD, the separator must be T (not a space), and the time HH:MM:SS[.fff…] with an optional Z or ±HH:MM offset.

Output precision is governed by the TimePrecision constants:

When an ISO string is assigned, the precision is auto-detected from the number of fractional digits present.

Example usage:

use org\iso\Iso8601DateTime;
use org\iso\TimePrecision;

// From ISO string
$dt = new Iso8601DateTime('2026-05-14T08:15:30+02:00');
echo $dt->datePart->year;     // 2026
echo $dt->timePart->hours;    // 8
echo $dt->timezone->getName();// "+02:00"

// Switch precision (re-renders iso)
$dt->precision = TimePrecision::MILLISECONDS;
echo $dt->iso;                // "2026-05-14T08:15:30.000+02:00"

// Round-trip via DateTimeImmutable
$dt->dateTime = new DateTimeImmutable('2030-01-01T00:00:00Z');
echo $dt->iso;                // "2030-01-01T00:00:00.000Z" (precision preserved)
Tags
link
https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations
author

Marc Alcaraz (ekameleon)

since
1.0.2

Table of Contents

Constants

FORMAT  : string = 'Y-m-d\TH:i:s'
The base format (without fractional seconds or offset): `Y-m-d\TH:i:s`.
PATTERN  : string = '/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...
Strict ISO 8601 date-time pattern: `YYYY-MM-DDTHH:MM:SS[.fff…][Z|±HH:MM]`.
TIME  : string = 'T'
Time designator (separates date and time components).
TIME_ZONE  : string = 'Z'
Timezone designator for UTC.
ZERO  : string = '1970-01-01T00:00:00Z'
Zero date-time constant (Unix epoch, UTC).

Properties

$datePart  : Iso8601Date
Derived {@see Iso8601Date} representing the calendar-date portion.
$dateTime  : DateTimeInterface
The internal immutable date-time representation.
$iso  : string
ISO string representation (e.g. "2026-05-14T08:15:30Z").
$precision  : string
Output precision used when rendering {@see iso}.
$timePart  : Iso8601Time
Derived {@see Iso8601Time} representing the time-of-day portion.
$timezone  : DateTimeZone|null
Timezone of the underlying date-time, or null if none is set.
$_dateTime  : DateTimeImmutable
$_iso  : string
$_precision  : string

Methods

__construct()  : mixed
Creates a new Iso8601DateTime instance.
__toString()  : string
String cast returns the ISO representation.
detectPrecision()  : string
Detects the {@see TimePrecision} of an ISO 8601 date-time string from its fractional-second component (0 digits → SECONDS, 1–3 → MILLISECONDS, ≥4 → MICROSECONDS).

Constants

FORMAT

The base format (without fractional seconds or offset): `Y-m-d\TH:i:s`.

public string FORMAT = 'Y-m-d\TH:i:s'

PATTERN

Strict ISO 8601 date-time pattern: `YYYY-MM-DDTHH:MM:SS[.fff…][Z|±HH:MM]`.

public string PATTERN = '/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])' . 'T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(?:\.(\d+))?' . '(Z|[+\-](?:[01]\d|2[0-3]):?[0-5]\d)?$/'

TIME

Time designator (separates date and time components).

public string TIME = 'T'

TIME_ZONE

Timezone designator for UTC.

public string TIME_ZONE = 'Z'

ZERO

Zero date-time constant (Unix epoch, UTC).

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

Properties

$datePart read-only virtual

Derived {@see Iso8601Date} representing the calendar-date portion.

public Iso8601Date $datePart

Returns a fresh object on each access; mutating it does not affect this instance.

Hooks
public Iso8601Date get

$dateTime virtual

The internal immutable date-time representation.

public DateTimeInterface $dateTime
Hooks
public DateTimeInterface get public set

$iso virtual

ISO string representation (e.g. "2026-05-14T08:15:30Z").

public string $iso
Hooks
public string get public set

$precision virtual

Output precision used when rendering {@see iso}.

public string $precision

Assigning a new precision regenerates the ISO string.

Tags
throws
InvalidArgumentException

If the value is not a TimePrecision constant.

Hooks
public string get public set

$timePart read-only virtual

Derived {@see Iso8601Time} representing the time-of-day portion.

public Iso8601Time $timePart

Returns a fresh object on each access; mutating it does not affect this instance.

Hooks
public Iso8601Time get

$timezone read-only virtual

Timezone of the underlying date-time, or null if none is set.

public DateTimeZone|null $timezone
Hooks
public DateTimeZone|null get

Methods

__construct()

Creates a new Iso8601DateTime instance.

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

ISO string (strict T separator), DateTime, or null for ZERO

Tags
throws
InvalidArgumentException

If the input is invalid

__toString()

String cast returns the ISO representation.

public __toString() : string
Return values
string

detectPrecision()

Detects the {@see TimePrecision} of an ISO 8601 date-time string from its fractional-second component (0 digits → SECONDS, 1–3 → MILLISECONDS, ≥4 → MICROSECONDS).

private static detectPrecision(string $iso) : string
Parameters
$iso : string
Return values
string
On this page

Search results