Temporal Types
Windwalker provides value objects for dates and times that do not need a time zone. They follow the Temporal model: each type holds one concept and nothing else.
PlainDate: a calendar date, such as a birthday.PlainTime: a wall-clock time, such as opening hours.PlainDateTime: a date and a time, without a zone.PlainYearMonth: a year and month, such as a billing period.PlainMonthDay: a month and day, such as an annual holiday.Instant: a fixed point on the timeline, stored in UTC.
Use these types when a value should not shift when the time zone changes. Use Chronos when the value needs a zone.
Calendar Dates
PlainDate::of() builds a date from its parts. An invalid date throws by default. Pass DateOverflow::Constrain to clamp instead.
use Windwalker\Core\DateTime\DateOverflow;
use Windwalker\Core\DateTime\PlainDate;
$birthday = PlainDate::of(1990, 5, 20);
echo $birthday->toIso(); // 1990-05-20
PlainDate::of(2023, 2, 29);
// ERROR: RangeException: Day 29 is out of range 1-28.
$date = PlainDate::of(2023, 2, 29, DateOverflow::Constrain);
echo $date->toIso(); // 2023-02-28Parse a string with parse(), or read today's date with today().
$date = PlainDate::parse('2024-03-15');
$today = PlainDate::today('Asia/Tokyo');Compare dates with compareTo().
$a = PlainDate::parse('2024-03-15');
$b = PlainDate::parse('2024-03-20');
// Negative when $a is earlier, zero when equal, positive when later
echo $a->compareTo($b) < 0 ? 'earlier' : 'later';Adding a period follows the same overflow rule. plus() and with() default to DateOverflow::Constrain, so the day is clamped instead of rolling into the next month.
$jan31 = PlainDate::of(2026, 1, 31);
echo $jan31->plus('P1M')->toIso(); // 2026-02-28
// The same clamp, written out explicitly
echo $jan31->plus('P1M', DateOverflow::Constrain)->toIso();
// 2026-02-28Wall-Clock Times
PlainTime::of() takes an hour, minute, second, and microsecond. All parts are optional and default to zero.
use Windwalker\Core\DateTime\PlainTime;
$open = PlainTime::of(9, 30);
echo $open->toIso(); // 09:30:00
$close = PlainTime::parse('18:00:00');
echo $close->compareTo($open) > 0 ? 'after' : 'before';Arithmetic on PlainTime wraps around midnight. It never moves to the next day, because a time has no date.
echo PlainTime::of(23, 30)->plus('PT1H')->toIso();
// 00:30:00INFO
PlainTime::parse() accepts fractions, such as 10:30:00.5, and the short form 10:30.
Date and Time Together
PlainDateTime joins a date and a time without a zone.
use Windwalker\Core\DateTime\PlainDate;
use Windwalker\Core\DateTime\PlainDateTime;
use Windwalker\Core\DateTime\PlainTime;
$meeting = PlainDateTime::of(2024, 3, 15, 9, 30);
// Keep the date, replace the time
$lunch = $meeting->withPlainTime(PlainTime::of(12));
echo $lunch->toIso(); // 2024-03-15T12:00:00
// Keep the date, reset the time to midnight
$start = $meeting->startOfDay();
echo $start->toIso(); // 2024-03-15T00:00:00
// Split into parts
$date = $meeting->toPlainDate(); // PlainDate
$time = $meeting->toPlainTime(); // PlainTimewithPlainTime(null) removes the time and returns the start of the day.
INFO
PlainDateTime::parse() does not accept a Z suffix. It expects a wall-clock value such as 2024-03-15T09:30:00. Use Instant for values that carry a zone.
Year-Month and Month-Day
Use PlainYearMonth for periods that have no day, and PlainMonthDay for values that repeat each year.
use Windwalker\Core\DateTime\PlainMonthDay;
use Windwalker\Core\DateTime\PlainYearMonth;
$billing = PlainYearMonth::of(2024, 3);
// The first day of the period
$start = $billing->toPlainDate();
echo $start->toIso(); // 2024-03-01
$holiday = PlainMonthDay::of(12, 25);
// The same holiday in a given year
$christmas = $holiday->toPlainDate(2024);
echo $christmas->toIso(); // 2024-12-25
// Feb 29 has no year to stay in; it is constrained by default
echo PlainMonthDay::of(2, 29)->toPlainDate(2026)->toIso();
// 2026-02-28INFO
PlainMonthDay has no year, so it cannot be compared with compareTo() or moved with plus(). Use equals() to test whether two values match.
Instants
Instant is a point on the timeline. Use it for event timestamps and ordering, because it does not depend on a time zone.
use Windwalker\Core\DateTime\Instant;
// A zone designator is required
$instant = Instant::parse('2024-03-15T08:30:00+08:00');
echo $instant->toIso(); // 2024-03-15T00:30:00Z
echo $instant->toEpochMilliseconds();
// Show it in a specific zone
$tokyo = $instant->toDateTime('Asia/Tokyo');
echo $tokyo->format('Y-m-d H:i:s');
// Convert to a Chronos for further work
$chronos = $instant->toChronos('Asia/Tokyo');Instant::now() returns the current instant.
Converting Values
from() reads the wall-clock fields of a Chronos, without changing the time zone. Instant::from() keeps the point in time instead.
use Windwalker\Core\DateTime\Chronos;
use Windwalker\Core\DateTime\Instant;
use Windwalker\Core\DateTime\PlainDate;
use Windwalker\Core\DateTime\PlainDateTime;
use Windwalker\Core\DateTime\PlainTime;
$chronos = Chronos::create('2026-03-05 23:30:00', 'Asia/Taipei');
echo PlainDate::from($chronos)->toIso(); // 2026-03-05
echo PlainTime::from($chronos)->toIso(); // 23:30:00
echo Instant::from($chronos)->toIso(); // 2026-03-05T15:30:00ZConvert back with toChronos(). The time zone defaults to UTC, not to the application's zone, so pass the zone you need.
$dateTime = PlainDateTime::of(2026, 3, 5, 10, 30);
echo $dateTime->toChronos('Asia/Taipei')->format('c');
// 2026-03-05T10:30:00+08:00
echo $dateTime->toChronos()->getTimezone()->getName();
// UTCThe global helpers in the Windwalker namespace convert arbitrary input. They are strict and do not call strtotime().
use function Windwalker\to_plain_date;
echo to_plain_date('2026-03-05')->toIso(); // 2026-03-05A conversion that would lose information throws. For example, to_plain_datetime() rejects a PlainDate, because it has no time.
Current Time
Clock returns the current value. It follows the clock set with Clock::set(), so tests can replace it with a MockClock.
use Windwalker\Core\DateTime\Clock;
echo Clock::instant()->toIso();
echo Clock::plainDate('Asia/Taipei')->toIso();
echo Clock::plainTime('Asia/Taipei')->toIso();
echo Clock::plainDateTime('Asia/Taipei')->toIso();Each type also has its own now() or today() method, such as PlainDate::today() and Instant::now().
Reading Fields
Fields are available as properties and as getter methods.
- Properties return zero-padded strings, which suit output.
- Getter methods return integers, which suit calculations.
$dateTime = PlainDateTime::of(2026, 3, 5, 9, 5, 7);
echo $dateTime->month; // 03
echo $dateTime->getMonth(); // 3
echo $dateTime->getHour(); // 9
echo $dateTime->getDayOfWeek(); // 4
echo $dateTime->getDaysInMonth(); // 31PlainDate and PlainDateTime also expose dayOfTheYear, which starts at 1, and weekOfYear. dayOfYear starts at 0, to match Chronos. Prefer dayOfTheYear in new code.
Changing Dates and Times
plus() and minus() accept an ISO 8601 duration string, a Duration, or a DateInterval. with() replaces named fields. Each call returns a new object.
$date = PlainDate::of(2026, 1, 31);
echo $date->plus('P1M')->toIso(); // 2026-02-28
echo $date->minus('P1D')->toIso(); // 2026-01-30
echo $date->with(month: 2)->toIso(); // 2026-02-28Pass DateOverflow::Native to keep PHP's rollover behavior.
echo $date->plus('P1M', DateOverflow::Native)->toIso();
// 2026-03-03PlainTime arithmetic wraps around midnight. PlainYearMonth accepts only year and month units.
echo PlainTime::of(23, 30)->plus('PT1H')->toIso();
// 00:30:00
// ERROR: InvalidArgumentException:
// PlainYearMonth does not support the interval unit "d".
PlainYearMonth::of(2024, 2)->plus('P1D');Comparing and Measuring Differences
compareTo(), equals(), isBefore(), and isAfter() compare values of the same type. Use PlainDate::compare() as a sort callback.
$dates = [
PlainDate::of(2026, 3, 1),
PlainDate::of(2026, 1, 31),
];
usort($dates, PlainDate::compare(...));until() and since() return a DateInterval. since() measures backwards from the other value. Pass a unit name as the second argument to choose the largest unit.
$start = PlainDate::of(2026, 1, 31);
$end = PlainDate::of(2026, 3, 1);
echo $start->diff($end, absolute: true)->days; // 29
echo $start->until($end, 'month')->format('%m months %d days');
// 1 months 1 daysRounding
PlainTime, PlainDateTime, and Instant provide round(). The smallest unit and the increment control the result. PlainDate has no round(), because it has no unit smaller than a day.
echo PlainTime::parse('23:59:59.6')->round('second')->toIso();
// 00:00:00
echo PlainTime::parse('10:07:30')->round('minute', 15)->toIso();
// 10:15:00
echo PlainDateTime::parse('2026-01-31T13:00')->round('day')->toIso();
// 2026-02-01T00:00:00The increment must divide the next larger unit evenly, such as 15 for minutes. round('day') accepts only an increment of 1.
// ERROR: InvalidArgumentException: Rounding increment of "day" must be 1.
PlainDateTime::parse('2026-01-31T13:00')->round('day', 2);Changing Time Zones
Use withTimezone() to show the same instant in another zone. Use withTimezoneKeepingLocal() to keep the wall-clock time and change the instant.
$taipei = Chronos::create('2026-03-05 10:00:00', 'Asia/Taipei');
echo $taipei->withTimezone('UTC')->format('c');
// 2026-03-05T02:00:00+00:00
echo $taipei->withTimezoneKeepingLocal('UTC')->format('c');
// 2026-03-05T10:00:00+00:00JSON and Strings
Every temporal type implements JsonSerializable and Stringable. Both output the toIso() format.
echo json_encode(PlainDate::of(2026, 3, 5));
// "2026-03-05"
echo json_encode(PlainDateTime::parse('2026-03-05T10:30:00.123456'));
// "2026-03-05T10:30:00.123456"
echo json_encode(Instant::parse('2026-03-05T10:30:00+08:00'));
// "2026-03-05T02:30:00Z"PlainMonthDay outputs MM-DD.
Entity Casts
Use PlainDateCast for a date column that should hold a PlainDate. It hydrates null, an empty string, and the MySQL 0000-00-00 sentinel to null.
use Windwalker\Core\DateTime\PlainDate;
use Windwalker\Core\DateTime\PlainDateCast;
use Windwalker\ORM\Attributes\CastNullable;
class Member
{
#[CastNullable(PlainDateCast::class)]
public ?PlainDate $birthday = null;
}INFO
PlainDateCast does no time zone conversion. A date column stores the same calendar date that the code reads.
Use PlainTimeCast for a time column that should hold a PlainTime. It accepts values from 00:00:00 to 23:59:59.
use Windwalker\Core\DateTime\PlainTime;
use Windwalker\Core\DateTime\PlainTimeCast;
use Windwalker\ORM\Attributes\CastNullable;
class Shift
{
#[CastNullable(PlainTimeCast::class)]
public ?PlainTime $startsAt = null;
}WARNING
PlainTimeCast throws InvalidArgumentException for values such as 838:59:59, which MySQL TIME columns can contain. Check the column range before you hydrate.
For values that need a time zone, use ServerTimeCast, described in ChronosService.