Calendar
Reference for the Calendar module: read the request's current time, and work with dates, times and datetimes as immutable data objects. Conversions to and from Unix timestamps and human-readable strings, UK bank holidays, and helpers for rendering dates in tables and forms.
This page is a pure reference. For how the framework fits together, see the Guide.
Calendar- the request's current time, and simple comparisons against it.CalendarBankHoliday- UK (England and Wales) bank holidays, listed per year.CalendarBankHolidayData- immutable data for a single bank holiday.CalendarDate- conversions and iteration for a calendar date.CalendarDateData- immutable year, month and day.CalendarDateTime- conversions for a combined date and time.CalendarDateTimeData- immutable date and time pair.CalendarTime- conversions for a time of day.CalendarTimeData- immutable time held as a total number of seconds.CalendarUi- table cells and form fields for dates, times and datetimes.
Calendar
The request's current time, captured once at startup, and readers for its parts as numbers and strings. Also compares a datetime against now.
GetCurrentDateAndTimeHumanReadable
Calendar::GetCurrentDateAndTimeHumanReadable()
The current date and time as a Y-m-d H:i:s string.
Returns string The current date and time.
GetCurrentDateString
Calendar::GetCurrentDateString($with_dashes = true)
The current date, as Y-m-d with dashes or Ymd without.
| Name | Type | Description |
|---|---|---|
$with_dashes | bool | True for Y-m-d, false for Ymd. |
Returns string The current date.
GetCurrentDay
Calendar::GetCurrentDay()
The day of the month of the current time.
Returns int The day of the month.
GetCurrentHour
Calendar::GetCurrentHour()
The hour of the current time, as a two-digit string.
Returns string The hour, 00 to 23.
GetCurrentMinute
Calendar::GetCurrentMinute()
The minute of the current time, as a two-digit string.
Returns string The minute, 00 to 59.
GetCurrentMonth
Calendar::GetCurrentMonth()
The month number of the current time.
Returns int The month, 1 to 12.
GetCurrentSecond
Calendar::GetCurrentSecond()
The second of the current time, as a two-digit string.
Returns string The second, 00 to 59.
GetCurrentTimestamp
Calendar::GetCurrentTimestamp()
The Unix timestamp captured for the current request.
Returns int The current timestamp.
GetCurrentTimeString
Calendar::GetCurrentTimeString($show_seconds = true, $with_colons = true)
The current time of day, with or without seconds and with or without colons.
| Name | Type | Description |
|---|---|---|
$show_seconds | bool | True to include seconds. |
$with_colons | bool | True to separate parts with colons. |
Returns string The current time of day.
GetCurrentYear
Calendar::GetCurrentYear()
The four-digit year of the current time.
Returns int The current year.
IsPast
Calendar::IsPast(CalendarDateTimeData $when): bool
Whether the given datetime is before the current time.
| Name | Type | Description |
|---|---|---|
$when | CalendarDateTimeData | The datetime to test. |
Returns bool True when the datetime is in the past.
SecondsSince
Calendar::SecondsSince(CalendarDateTimeData $when): int
The number of seconds from the given datetime to now, negative when it is in the future.
| Name | Type | Description |
|---|---|---|
$when | CalendarDateTimeData | The datetime to measure from. |
Returns int The elapsed seconds.
CalendarBankHoliday
UK (England and Wales) bank holidays, listed explicitly per year. Years without an entry return no holidays.
BankHolidays
CalendarBankHoliday::BankHolidays(int $year): array
All bank holidays for a year, empty when the year is not listed.
| Name | Type | Description |
|---|---|---|
$year | int | Four-digit year. |
Returns array A list of CalendarBankHolidayData.
IsBankHoliday
CalendarBankHoliday::IsBankHoliday(string $date): bool
Whether a date is a bank holiday.
| Name | Type | Description |
|---|---|---|
$date | string | Date in YYYY-MM-DD format. |
Returns bool True when the date is a bank holiday.
OptionalNameByDate
CalendarBankHoliday::OptionalNameByDate(string $date): ?string
The bank holiday name for a date, or null when it is not a bank holiday.
| Name | Type | Description |
|---|---|---|
$date | string | Date in YYYY-MM-DD format. |
Returns ?string The holiday name, or null.
CalendarBankHolidayData
Immutable data for a single bank holiday. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$data->name | string | Name of the holiday, for example Christmas Day (readonly). |
$data->date | string | Date in YYYY-MM-DD format (readonly). |
__construct
new CalendarBankHolidayData(string $name, string $date)
Create bank holiday data from a name and date.
| Name | Type | Description |
|---|---|---|
$name | string | Name of the holiday. |
$date | string | Date in YYYY-MM-DD format. |
Returns CalendarBankHolidayData
CalendarDate
Conversions for a calendar date to and from Unix timestamps and strings, month names, the current date, and iteration back over recent days, months and years.
EachPreviousDay
CalendarDate::EachPreviousDay(int $numDays, callable $callback): void
Call the callback for each of the last N days, oldest first, ending today.
| Name | Type | Description |
|---|---|---|
$numDays | int | Number of days to iterate. |
$callback | callable | Receives a CalendarDateData for each day. |
Returns void
EachPreviousMonth
CalendarDate::EachPreviousMonth(int $numMonths, callable $callback): void
Call the callback for the first day of each of the last N months, oldest first, handling year rollover.
| Name | Type | Description |
|---|---|---|
$numMonths | int | Number of months to iterate. |
$callback | callable | Receives a CalendarDateData for the first day of each month. |
Returns void
EachPreviousYear
CalendarDate::EachPreviousYear(int $numYears, callable $callback): void
Call the callback for January 1st of each of the last N years, oldest first.
| Name | Type | Description |
|---|---|---|
$numYears | int | Number of years to iterate. |
$callback | callable | Receives a CalendarDateData for January 1st of each year. |
Returns void
FromUnixTimestamp
CalendarDate::FromUnixTimestamp(int $timestamp): CalendarDateData
Build a date from a Unix timestamp.
| Name | Type | Description |
|---|---|---|
$timestamp | int | Unix timestamp. |
Returns CalendarDateData The date.
MonthName
CalendarDate::MonthName(int $month): string
The full month name for a month number.
| Name | Type | Description |
|---|---|---|
$month | int | Month number, 1 to 12. |
Returns string The full month name.
Now
CalendarDate::Now(): CalendarDateData
Today's date, from the current time.
Returns CalendarDateData The current date.
ToDatabaseDate
CalendarDate::ToDatabaseDate(CalendarDateData $date): string
The date as a YYYY-MM-DD string for database storage.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date to format. |
Returns string The date with dashes.
ToHumanReadable
CalendarDate::ToHumanReadable(CalendarDateData $date): string
The date as a readable string, for example 1st Jan 2026.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date to format. |
Returns string The readable date.
ToUnixTimestamp
CalendarDate::ToUnixTimestamp(CalendarDateData $date): int
The Unix timestamp for midnight at the start of the date.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date to convert. |
Returns int The Unix timestamp.
ToYYYYMMDD
CalendarDate::ToYYYYMMDD(CalendarDateData $date, $dashes): string
The date as YYYY-MM-DD with dashes, or YYYYMMDD without.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date to format. |
$dashes | bool | True to include dashes. |
Returns string The formatted date.
CalendarDateData
Immutable year, month and day. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$date->year | int | Four-digit year (readonly). |
$date->month | int | Month, 1 to 12 (readonly). |
$date->day | int | Day of the month (readonly). |
__construct
new CalendarDateData(int $year = 2000, int $month = 1, int $day = 1)
Create a date from a year, month and day.
| Name | Type | Description |
|---|---|---|
$year | int | Four-digit year. |
$month | int | Month, 1 to 12. |
$day | int | Day of the month. |
Returns CalendarDateData
CalendarDateTime
Conversions for a combined date and time to and from Unix timestamps and strings, including null-safe variants and the current datetime.
FromOptionalUnixTimestamp
CalendarDateTime::FromOptionalUnixTimestamp(int|null $timestamp): CalendarDateTimeData|null
Build a datetime from a Unix timestamp, or null when the timestamp is null.
| Name | Type | Description |
|---|---|---|
$timestamp | int|null | Unix timestamp, or null. |
Returns CalendarDateTimeData|null The datetime, or null.
FromUnixTimestamp
CalendarDateTime::FromUnixTimestamp($timestamp): CalendarDateTimeData
Build a datetime from a Unix timestamp.
| Name | Type | Description |
|---|---|---|
$timestamp | int | Unix timestamp. |
Returns CalendarDateTimeData The datetime.
Now
CalendarDateTime::Now(): CalendarDateTimeData
The current datetime, from the current time.
Returns CalendarDateTimeData The current datetime.
ToHumanReadable
CalendarDateTime::ToHumanReadable(CalendarDateTimeData $dateTime): string
The datetime as a readable date and time, without seconds.
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData | The datetime to format. |
Returns string The readable datetime.
ToHumanReadableWithSeconds
CalendarDateTime::ToHumanReadableWithSeconds(CalendarDateTimeData $dateTime): string
The datetime as a readable date and time, including seconds (HH:MM:SS).
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData | The datetime to format. |
Returns string The readable datetime with seconds.
ToOptionalUnixTimestamp
CalendarDateTime::ToOptionalUnixTimestamp(CalendarDateTimeData|null $dateTime): int|null
The Unix timestamp for a datetime, or null when the datetime is null.
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData|null | The datetime to convert, or null. |
Returns int|null The Unix timestamp, or null.
ToUnixTimestamp
CalendarDateTime::ToUnixTimestamp(CalendarDateTimeData $dateTime): int
The Unix timestamp for a datetime.
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData | The datetime to convert. |
Returns int The Unix timestamp.
ToYYYYMMDDHHMM
CalendarDateTime::ToYYYYMMDDHHMM(CalendarDateTimeData $dateTime): string
The datetime as a YYYY-MM-DDTHH:MM string, suitable for a datetime-local input.
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData | The datetime to format. |
Returns string The formatted datetime.
CalendarDateTimeData
Immutable date and time pair. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$dateTime->date | CalendarDateData | The date part (readonly). |
$dateTime->time | CalendarTimeData | The time part (readonly). |
__construct
new CalendarDateTimeData(CalendarDateData $date = new CalendarDateData(), CalendarTimeData $time = new CalendarTimeData())
Create a datetime from a date and a time.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date part. |
$time | CalendarTimeData | The time part. |
Returns CalendarDateTimeData
CalendarTime
Conversions for a time of day held as a total number of seconds: its parts, its total seconds, a readable string, and construction from a Unix timestamp.
FromUnixTimestamp
CalendarTime::FromUnixTimestamp($timestamp): CalendarTimeData
Build a time of day from a Unix timestamp, taking the hour, minute and second.
| Name | Type | Description |
|---|---|---|
$timestamp | int | Unix timestamp. |
Returns CalendarTimeData The time of day.
GetDay
CalendarTime::GetDay(CalendarTimeData $time): int
The number of whole days in the total seconds.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The number of days.
GetHour
CalendarTime::GetHour(CalendarTimeData $time): int
The hour of the day, 0 to 23.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The hour.
GetMillisecond
CalendarTime::GetMillisecond(CalendarTimeData $time): int
The millisecond part of the time, 0 to 999.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The millisecond.
GetMinute
CalendarTime::GetMinute(CalendarTimeData $time): int
The minute of the hour, 0 to 59.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The minute.
GetNanosecond
CalendarTime::GetNanosecond(CalendarTimeData $time): int
The sub-millisecond part of the time, derived from the fractional seconds.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The nanosecond part.
GetSecond
CalendarTime::GetSecond(CalendarTimeData $time): int
The second of the minute, 0 to 59.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The second.
ToHumanReadable
CalendarTime::ToHumanReadable(CalendarTimeData $time): string
The time as an H:MM string.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns string The readable time.
ToSeconds
CalendarTime::ToSeconds(CalendarTimeData $time): int
The time of day as whole seconds since midnight, ignoring any day part.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time value. |
Returns int The seconds since midnight.
CalendarTimeData
Immutable time held as a total number of seconds. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$time->totalSeconds | float | Total seconds represented by the time (readonly). |
__construct
new CalendarTimeData(float $totalSeconds = 0)
Create a time from a total number of seconds.
| Name | Type | Description |
|---|---|---|
$totalSeconds | float | Total seconds. |
Returns CalendarTimeData
CalendarUi
Helpers that render dates, times and datetimes into the Ui library: table cells and a datetime form field.
FormDateTime
CalendarUi::FormDateTime(string $name, string $label, CalendarDateTimeData $value): void
Render a datetime-local input field with a label and current value.
| Name | Type | Description |
|---|---|---|
$name | string | Field name. |
$label | string | Field label. |
$value | CalendarDateTimeData | Current datetime value. |
Returns void
TableCellDate
CalendarUi::TableCellDate(CalendarDateData $date): void
Render a date as a readable table cell.
| Name | Type | Description |
|---|---|---|
$date | CalendarDateData | The date to render. |
Returns void
TableCellDateTime
CalendarUi::TableCellDateTime(CalendarDateTimeData $dateTime): void
Render a datetime as a readable table cell.
| Name | Type | Description |
|---|---|---|
$dateTime | CalendarDateTimeData | The datetime to render. |
Returns void
TableCellTime
CalendarUi::TableCellTime(CalendarTimeData $time): void
Render a time as a readable table cell.
| Name | Type | Description |
|---|---|---|
$time | CalendarTimeData | The time to render. |
Returns void
TableCellTimestamp
CalendarUi::TableCellTimestamp(int|null $optionalTimestamp): void
Render a Unix timestamp as a readable table cell, showing (none) for null or zero.
| Name | Type | Description |
|---|---|---|
$optionalTimestamp | int|null | Unix timestamp, or null or zero for an empty cell. |
Returns void