Iso8601Date
Represents and manipulates ISO 8601 calendar date strings (without time component).
This class provides a convenient wrapper around PHP's DateTimeImmutable for
handling dates expressed in ISO 8601 extended format (YYYY-MM-DD). It maintains
synchronization between the ISO 8601 string representation and the internal
immutable date object.
Only the extended format is accepted in the iso setter; the basic format
(YYYYMMDD) is rejected by design. Calendar validity is enforced via
checkdate() through isIso8601Date().
ISO 8601 date examples:
- "2026-05-14"
- "2024-02-29" (leap year)
Example usage:
use org\iso\Iso8601Date;
// From ISO 8601 string
$date = new Iso8601Date('2026-05-14');
echo $date->year; // 2026
echo $date->month; // 5
echo $date->day; // 14
echo $date->weekday; // 4 (Thursday, ISO 1-7 from Monday)
echo $date->dayOfYear; // 134 (1-based)
// From DateTimeInterface
$dt = new DateTimeImmutable('2024-02-29');
$date = new Iso8601Date($dt);
echo $date->iso; // "2024-02-29"
// Round-trip via setter
$date->iso = '2030-12-31';
echo $date->year; // 2030
Tags
Table of Contents
Constants
- DAY : string = 'd'
- The 'day' format character (numeric, zero-padded).
- DAY_OF_YEAR : string = 'z'
- The 'day of year' format character (0-based in PHP; this class exposes a 1-based value).
- FORMAT : string = 'Y-m-d'
- The full date format (`Y-m-d`).
- MONTH : string = 'm'
- The 'month' format character (numeric, zero-padded).
- PATTERN : string = '/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...
- ISO 8601 calendar date pattern (extended format only): `YYYY-MM-DD`.
- WEEKDAY : string = 'N'
- The ISO-8601 'day of week' format character (1 = Monday, 7 = Sunday).
- YEAR : string = 'Y'
- The 'year' format character (4-digit year).
- ZERO : string = '1970-01-01'
- Epoch date constant (Unix epoch, used as the default zero value).
Properties
- $date : DateTimeInterface
- The internal immutable date representation.
- $day : int
- Gets the day-of-month component (1–31).
- $dayOfYear : int
- Gets the 1-based day of year (1 = January 1st, 365 or 366 = December 31st).
- $iso : string
- ISO string representation (e.g. "2026-05-14").
- $month : int
- Gets the month component (1–12).
- $weekday : int
- Gets the ISO 8601 day-of-week (1 = Monday, 7 = Sunday).
- $year : int
- Gets the 4-digit year (e.g. 2026).
- $_date : DateTimeImmutable
- The internal DateTimeImmutable representing the date.
- $_iso : string
Methods
- __construct() : mixed
- Creates a new Iso8601Date instance.
- __toString() : string
- String cast returns the ISO representation.
Constants
DAY
The 'day' format character (numeric, zero-padded).
public
string
DAY
= 'd'
DAY_OF_YEAR
The 'day of year' format character (0-based in PHP; this class exposes a 1-based value).
public
string
DAY_OF_YEAR
= 'z'
FORMAT
The full date format (`Y-m-d`).
public
string
FORMAT
= 'Y-m-d'
MONTH
The 'month' format character (numeric, zero-padded).
public
string
MONTH
= 'm'
PATTERN
ISO 8601 calendar date pattern (extended format only): `YYYY-MM-DD`.
public
string
PATTERN
= '/^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/'
WEEKDAY
The ISO-8601 'day of week' format character (1 = Monday, 7 = Sunday).
public
string
WEEKDAY
= 'N'
YEAR
The 'year' format character (4-digit year).
public
string
YEAR
= 'Y'
ZERO
Epoch date constant (Unix epoch, used as the default zero value).
public
string
ZERO
= '1970-01-01'
Properties
$date virtual
The internal immutable date representation.
public
DateTimeInterface
$date
Hooks
public
DateTimeInterface
get
public
set
$day read-only virtual
Gets the day-of-month component (1–31).
public
int
$day
Hooks
public
int
get
$dayOfYear read-only virtual
Gets the 1-based day of year (1 = January 1st, 365 or 366 = December 31st).
public
int
$dayOfYear
Hooks
public
int
get
$iso virtual
ISO string representation (e.g. "2026-05-14").
public
string
$iso
Hooks
public
string
get
public
set
$month read-only virtual
Gets the month component (1–12).
public
int
$month
Hooks
public
int
get
$weekday read-only virtual
Gets the ISO 8601 day-of-week (1 = Monday, 7 = Sunday).
public
int
$weekday
Hooks
public
int
get
$year read-only virtual
Gets the 4-digit year (e.g. 2026).
public
int
$year
Hooks
public
int
get
$_date
The internal DateTimeImmutable representing the date.
private
DateTimeImmutable
$_date
$_iso
private
string
$_iso
Methods
__construct()
Creates a new Iso8601Date instance.
public
__construct([string|DateTimeInterface|null $date = null ]) : mixed
Parameters
- $date : string|DateTimeInterface|null = null
-
ISO extended string, DateTime, or null for the epoch (ZERO)
Tags
__toString()
String cast returns the ISO representation.
public
__toString() : string