#Dates

Phuture\Coherence\Dates

class Dates extends StaticClass

Comprehensive date and time manipulation utility class with full timezone support.

This utility class provides a complete toolkit for date and time operations, covering creation, formatting, arithmetic, comparison, and inspection of date values. Every method works with PHP's built-in DateTimeImmutable to keep original values unchanged and prevent accidental side effects.

Key features:

• Creation: Build date/time values from scratch, strings, timestamps, or custom formats
• Timezone awareness: Every creation method accepts an explicit timezone; all operations preserve or convert timezones without data loss
• Formatting: Common output formats plus fully custom strftime-style format strings
• Arithmetic: Add or remove any unit from seconds to years
• Comparison: Check order, equality, and same-period relationships between two dates
• Difference: Compute elapsed time in any unit between two dates
• Inspection: Read individual components (year, month, day, hour …) and ask boolean questions (is today?, is weekend?, is leap year? …)
• Boundaries: Jump to the start or end of any period (day, week, month, year)
• Fluent interface: Call Dates::of() to obtain a chainable \Phuture\Coherence\Type\Dates wrapper

#Constants

#MARKER_DAY_OF_WEEK

const MARKER_DAY_OF_WEEK = "\xFD\x00"

Marker byte sequence for day.js d token — day of week (0–6) with no leading zero. PHP has w but it must not be used in format strings that go through strtr.

#MARKER_MINUTES_NO_PAD

const MARKER_MINUTES_NO_PAD = "\xFD\x02"

Marker byte sequence for day.js m token — minutes (0–59) with no leading zero. PHP's i always produces a leading zero; there is no zero-padded alternative.

#MARKER_SECONDS_NO_PAD

const MARKER_SECONDS_NO_PAD = "\xFD\x03"

Marker byte sequence for day.js s token — seconds (0–59) with no leading zero. PHP's s always produces a leading zero; there is no zero-padded alternative.

#MARKER_SHORT_DAY_NAME

const MARKER_SHORT_DAY_NAME = "\xFD\x01"

Marker byte sequence for day.js dd token — two-letter day name (Su, Mo, Tu …). PHP has no native format character for two-letter day abbreviations.

#Methods

#addBusinessDays()

public static function addBusinessDays(DateTimeImmutable|string $date, int $days): DateTimeImmutable

Adds a number of business days to a date/time value.

Returns a new date/time value that is the given number of business days (Monday through Friday) later than the original. Weekends (Saturday and Sunday) are skipped and do not count toward the total. A negative value moves backward through the calendar, also skipping weekends.

Example:

1use Phuture\Coherence\Dates;
2
3// Wednesday + 3 business days = Monday
4$date = Dates::parse('2026-04-22'); // Wednesday
5$result = Dates::addBusinessDays($date, 3); // 2026-04-27 (Monday)

Returns DateTimeImmutable — A new date/time value with the business days added

See also

• \Phuture\Coherence\Dates::addDays()
• \Phuture\Coherence\Dates::diffInBusinessDays()

#addDays()

public static function addDays(DateTimeImmutable|string $date, int $days): DateTimeImmutable

Adds a number of days to a date/time value.

Returns a new date/time value that is the given number of days later than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::addDays($date, 10); // '2026-05-01'

Returns DateTimeImmutable — A new date/time value with the days added

See also

• \Phuture\Coherence\Dates::removeDays()

#addHours()

public static function addHours(DateTimeImmutable|string $date, int $hours): DateTimeImmutable

Adds a number of hours to a date/time value.

Returns a new date/time value that is the given number of hours later than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::addHours($date, 3); // '2026-04-21 17:30:00'

Returns DateTimeImmutable — A new date/time value with the hours added

See also

• \Phuture\Coherence\Dates::removeHours()

#addMinutes()

public static function addMinutes(DateTimeImmutable|string $date, int $minutes): DateTimeImmutable

Adds a number of minutes to a date/time value.

Returns a new date/time value that is the given number of minutes later than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::addMinutes($date, 45); // '2026-04-21 15:15:00'

Returns DateTimeImmutable — A new date/time value with the minutes added

See also

• \Phuture\Coherence\Dates::removeMinutes()

#addMonths()

public static function addMonths(DateTimeImmutable|string $date, int $months): DateTimeImmutable

Adds a number of months to a date/time value.

Returns a new date/time value that is the given number of months later than the original. When the resulting day does not exist in the target month (e.g. adding 1 month to January 31 gives March 3 or 2 in a leap year), PHP overflows to the next month.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-01-15');
4$result = Dates::addMonths($date, 3); // '2026-04-15'

Returns DateTimeImmutable — A new date/time value with the months added

See also

• \Phuture\Coherence\Dates::removeMonths()

#addSeconds()

public static function addSeconds(DateTimeImmutable|string $date, int $seconds): DateTimeImmutable

Adds a number of seconds to a date/time value.

Returns a new date/time value that is the given number of seconds later than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::addSeconds($date, 90); // '2026-04-21 14:31:30'

Returns DateTimeImmutable — A new date/time value with the seconds added

See also

• \Phuture\Coherence\Dates::removeSeconds()

#addWeeks()

public static function addWeeks(DateTimeImmutable|string $date, int $weeks): DateTimeImmutable

Adds a number of weeks to a date/time value.

Returns a new date/time value that is the given number of weeks later than the original. One week equals exactly 7 days.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::addWeeks($date, 2); // '2026-05-05'

Returns DateTimeImmutable — A new date/time value with the weeks added

See also

• \Phuture\Coherence\Dates::removeWeeks()

#addYears()

public static function addYears(DateTimeImmutable|string $date, int $years): DateTimeImmutable

Adds a number of years to a date/time value.

Returns a new date/time value that is the given number of years later than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::addYears($date, 5); // '2031-04-21'

Returns DateTimeImmutable — A new date/time value with the years added

See also

• \Phuture\Coherence\Dates::removeYears()

#create()

public static function create(int $year, int $month, int $day, int $hour = 0, int $minute = 0, int $second = 0, ?string $timezone = null): DateTimeImmutable

Creates a date/time value from individual date and time components.

Builds a precise moment in time by specifying each component separately. This is the safest way to create dates when you have distinct year, month, day, hour, minute, and second values from separate sources.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::create(2026, 12, 25); // Christmas midnight UTC
4$meeting = Dates::create(2026, 4, 21, 14, 30, 0, 'Europe/Paris'); // 14:30 Paris time

Returns DateTimeImmutable — The constructed date/time value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is invalid or any component is out of its valid range

See also

• \Phuture\Coherence\Dates::now()
• \Phuture\Coherence\Dates::parse()

#diffInBusinessDays()

public static function diffInBusinessDays(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of business days between two date/time values.

Returns the absolute (always positive) number of weekdays (Monday through Friday) that fall strictly between the two calendar dates. Both the start and end dates are excluded from the count. Weekends (Saturday and Sunday) are never counted.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-20'); // Monday
4$end = Dates::parse('2026-04-25');   // Saturday
5Dates::diffInBusinessDays($start, $end); // 4 (Tue, Wed, Thu, Fri)

Returns int — The number of business days between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInDays()
• \Phuture\Coherence\Dates::addBusinessDays()

#diffInDays()

public static function diffInDays(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete days between two date/time values.

Returns the absolute (always positive) number of full days between the two dates. Partial days are discarded — for example, 23 hours returns 0.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-01');
4$end = Dates::parse('2026-04-21');
5Dates::diffInDays($start, $end); // 20

Returns int — The number of complete days between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInHours()
• \Phuture\Coherence\Dates::diffInWeeks()

#diffInHours()

public static function diffInHours(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete hours between two date/time values.

Returns the absolute (always positive) number of full hours between the two dates. Partial hours are discarded — for example, 59 minutes returns 0.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-21 08:00:00');
4$end = Dates::parse('2026-04-21 20:30:00');
5Dates::diffInHours($start, $end); // 12

Returns int — The number of complete hours between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInMinutes()
• \Phuture\Coherence\Dates::diffInDays()

#diffInMinutes()

public static function diffInMinutes(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete minutes between two date/time values.

Returns the absolute (always positive) number of full minutes between the two dates. Partial minutes are discarded — for example, 89 seconds returns 1.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-21 14:00:00');
4$end = Dates::parse('2026-04-21 15:30:00');
5Dates::diffInMinutes($start, $end); // 90

Returns int — The number of complete minutes between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInSeconds()
• \Phuture\Coherence\Dates::diffInHours()

#diffInMonths()

public static function diffInMonths(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete months between two date/time values.

Returns the absolute (always positive) number of full calendar months between the two dates using PHP's DateInterval. Partial months are discarded.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-01-15');
4$end = Dates::parse('2026-04-10');
5Dates::diffInMonths($start, $end); // 2 (not 3, because April 10 < January 15 in day)

Returns int — The number of complete months between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInWeeks()
• \Phuture\Coherence\Dates::diffInYears()

#diffInSeconds()

public static function diffInSeconds(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete seconds between two date/time values.

Returns the absolute (always positive) number of full seconds between the two dates. The order of the arguments does not matter — the result is always non-negative.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-21 14:00:00');
4$end = Dates::parse('2026-04-21 14:01:30');
5Dates::diffInSeconds($start, $end); // 90

Returns int — The number of complete seconds between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInMinutes()
• \Phuture\Coherence\Dates::diffInHours()

#diffInWeeks()

public static function diffInWeeks(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete weeks between two date/time values.

Returns the absolute (always positive) number of full weeks between the two dates. Partial weeks are discarded — for example, 6 days returns 0.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2026-04-07');
4$end = Dates::parse('2026-04-21');
5Dates::diffInWeeks($start, $end); // 2

Returns int — The number of complete weeks between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInDays()
• \Phuture\Coherence\Dates::diffInMonths()

#diffInYears()

public static function diffInYears(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): int

Calculates the number of complete years between two date/time values.

Returns the absolute (always positive) number of full calendar years between the two dates using PHP's DateInterval. Partial years are discarded.

Example:

1use Phuture\Coherence\Dates;
2
3$start = Dates::parse('2020-06-15');
4$end = Dates::parse('2026-04-10');
5Dates::diffInYears($start, $end); // 5

Returns int — The number of complete years between the two values (always non-negative)

See also

• \Phuture\Coherence\Dates::diffInMonths()

#endOfDay()

public static function endOfDay(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the very end of its day (23:59:59).

Keeps the same date and timezone but sets the time to one second before midnight.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:45');
4$result = Dates::endOfDay($date); // '2026-04-21 23:59:59'

Returns DateTimeImmutable — A new date/time value at 23:59:59 on the same calendar day

See also

• \Phuture\Coherence\Dates::startOfDay()

#endOfMonth()

public static function endOfMonth(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the last day of the same month at 23:59:59.

Automatically accounts for months with different lengths, including February in leap years.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-15');
4$result = Dates::endOfMonth($date); // '2026-04-30 23:59:59'

Returns DateTimeImmutable — A new date/time value at the last day of the month at 23:59:59

See also

• \Phuture\Coherence\Dates::startOfMonth()

#endOfWeek()

public static function endOfWeek(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the Sunday of the same ISO week at 23:59:59.

The ISO week ends on Sunday. The time is set to 23:59:59.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21'); // Tuesday
4$result = Dates::endOfWeek($date); // '2026-04-26 23:59:59' (Sunday)

Returns DateTimeImmutable — A new date/time value at Sunday 23:59:59 of the same week

See also

• \Phuture\Coherence\Dates::startOfWeek()

#endOfYear()

public static function endOfYear(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to December 31st of the same year at 23:59:59.

Advances to December 31 and sets the time to 23:59:59.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::endOfYear($date); // '2026-12-31 23:59:59'

Returns DateTimeImmutable — A new date/time value at December 31st of the same year at 23:59:59

See also

• \Phuture\Coherence\Dates::startOfYear()

#equals()

public static function equals(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether two date/time values represent the exact same moment in time.

Both dates are compared as absolute points in time (Unix timestamps). Two dates in different timezones that represent the same moment will be equal.

Example:

1use Phuture\Coherence\Dates;
2
3$utc = Dates::parse('2026-04-21 12:00:00', 'UTC');
4$ny = Dates::parse('2026-04-21 08:00:00', 'America/New_York');
5Dates::equals($utc, $ny); // true — same moment, different timezones

Returns bool — Returns true if both values represent the same point in time

See also

• \Phuture\Coherence\Dates::isBefore()
• \Phuture\Coherence\Dates::isAfter()

#format()

public static function format(DateTimeImmutable|string $date, string $format): string

Formats a date/time value using either PHP native or day.js-style format tokens.

This method supports two format styles and automatically detects which one you are using based on the format string contents:

PHP native format — when the string contains only single-character format codes (the same characters as PHP's date() function):

day.js-style tokens — when the string contains multi-character tokens or bracket-escaped text ([...]):

To include literal text in a day.js-style format, wrap it in square brackets. For example, [at] outputs the word "at" without transforming the letters.

Example:

 1use Phuture\Coherence\Dates;
 2
 3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
 4
 5// PHP native format (single-character codes)
 6Dates::format($date, 'Y-m-d'); // '2026-04-21'
 7Dates::format($date, 'd/m/Y H:i'); // '21/04/2026 14:30'
 8Dates::format($date, 'l, F j, Y'); // 'Tuesday, April 21, 2026'
 9
10// day.js-style tokens (multi-character codes)
11Dates::format($date, 'YYYY-MM-DD'); // '2026-04-21'
12Dates::format($date, 'DD/MM/YYYY HH:mm'); // '21/04/2026 14:30'
13Dates::format($date, 'dddd, MMMM D, YYYY'); // 'Tuesday, April 21, 2026'
14Dates::format($date, 'h:mm A'); // '2:30 PM'
15Dates::format($date, '[Today is] dddd'); // 'Today is Tuesday'

Returns string — The formatted date/time string

See also

• \Phuture\Coherence\Dates::toDate()
• \Phuture\Coherence\Dates::toDateTime()

#fromFormat()

public static function fromFormat(string $format, string $dateString, ?string $timezone = null): DateTimeImmutable

Creates a date/time value from a string using an explicit format pattern.

Use this when you know the exact format of your date string and want strict parsing. Supports both PHP native format characters and day.js-style tokens — the format style is auto-detected the same way as {@see format()}.

Example:

1use Phuture\Coherence\Dates;
2
3// PHP native format
4$date = Dates::fromFormat('d/m/Y', '21/04/2026');
5$date = Dates::fromFormat('Y-m-d H:i:s', '2026-04-21 14:30:00', 'Europe/London');
6
7// day.js-style tokens
8$date = Dates::fromFormat('DD/MM/YYYY', '21/04/2026');
9$date = Dates::fromFormat('YYYY-MM-DD HH:mm:ss', '2026-04-21 14:30:00', 'Europe/London');

Returns DateTimeImmutable — The parsed date and time value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the format does not match the date string or the timezone is invalid

See also

• \Phuture\Coherence\Dates::parse()
• \Phuture\Coherence\Dates::format()

#fromRelative()

public static function fromRelative(string $expression, DateTimeImmutable|string|null $relativeTo = null, ?string $timezone = null): DateTimeImmutable

Parses a relative date expression into an absolute date/time value.

Converts a human-readable relative expression like '3 days', '2 hours ago', or 'next Monday' into a concrete DateTimeImmutable value. The expression is evaluated relative to a reference date, which defaults to the current moment when not provided.

This method supports everything PHP's strtotime() accepts, plus the 'in X units' pattern that PHP does not handle natively:

• PHP native: '+2 days', '-1 week', 'next Monday', 'last day of next month'
• Natural language: '3 days ago', '2 hours ago', '1 week'
• Extended: 'in 3 days', 'in 2 hours', 'in 1 week', 'in 5 minutes'

Example:

 1use Phuture\Coherence\Dates;
 2
 3$ref = Dates::parse('2026-04-21 12:00:00', 'UTC');
 4
 5// PHP native relative expressions
 6Dates::fromRelative('+3 days', $ref);  // 2026-04-24 12:00:00
 7Dates::fromRelative('-1 week', $ref);  // 2026-04-14 12:00:00
 8
 9// Natural language
10Dates::fromRelative('2 days ago', $ref); // 2026-04-19 12:00:00
11
12// Extended 'in X units' pattern
13Dates::fromRelative('in 5 hours', $ref); // 2026-04-21 17:00:00
14
15// Without a reference date, resolves against the current moment
16Dates::fromRelative('tomorrow');

Returns DateTimeImmutable — The absolute date/time that the expression resolves to

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the expression cannot be parsed or the timezone is invalid

See also

• \Phuture\Coherence\Dates::parse()
• \Phuture\Coherence\Dates::toRelative()

#fromTimestamp()

public static function fromTimestamp(int $timestamp, ?string $timezone = null): DateTimeImmutable

Creates a date/time value from a Unix timestamp.

A Unix timestamp is the number of seconds that have elapsed since 1 January 1970 00:00:00 UTC. This is the format returned by PHP's time() function.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::fromTimestamp(1745236800); // UTC
4$date = Dates::fromTimestamp(1745236800, 'America/Los_Angeles'); // same moment, LA time

Returns DateTimeImmutable — The date and time represented by the timestamp

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is invalid

See also

• \Phuture\Coherence\Dates::toTimestamp()

#getDay()

public static function getDay(DateTimeImmutable|string $date): int

Returns the day of the month for a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4Dates::getDay($date); // 21

Returns int — The day of the month as an integer from 1 to 31

See also

• \Phuture\Coherence\Dates::getMonth()
• \Phuture\Coherence\Dates::getYear()

#getDayOfWeek()

public static function getDayOfWeek(DateTimeImmutable|string $date): int

Returns the day of the week for a date/time value.

The returned value follows the ISO 8601 standard where Monday is 1 and Sunday is 7.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21'); // Tuesday
4Dates::getDayOfWeek($date); // 2

Returns int — The ISO 8601 day of the week: 1 (Monday) through 7 (Sunday)

See also

• \Phuture\Coherence\Dates::getDayOfYear()
• \Phuture\Coherence\Dates::isWeekend()

#getDayOfYear()

public static function getDayOfYear(DateTimeImmutable|string $date): int

Returns the day of the year for a date/time value.

January 1 is day 1, December 31 is day 365 (or 366 in a leap year).

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-01-31');
4Dates::getDayOfYear($date); // 31

Returns int — The day of the year as an integer from 1 to 366

See also

• \Phuture\Coherence\Dates::getDayOfWeek()
• \Phuture\Coherence\Dates::getWeekOfYear()

#getDaysInMonth()

public static function getDaysInMonth(DateTimeImmutable|string $date): int

Returns the number of days in the month of a date/time value.

Takes leap years into account when calculating February.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-02-01');
4Dates::getDaysInMonth($date); // 28
5
6$leapDate = Dates::parse('2024-02-01');
7Dates::getDaysInMonth($leapDate); // 29

Returns int — The number of days in the month, from 28 to 31

See also

• \Phuture\Coherence\Dates::isLeapYear()

#getHour()

public static function getHour(DateTimeImmutable|string $date): int

Returns the hour of a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4Dates::getHour($date); // 14

Returns int — The hour as an integer from 0 to 23

See also

• \Phuture\Coherence\Dates::getMinute()
• \Phuture\Coherence\Dates::getSecond()

#getMinute()

public static function getMinute(DateTimeImmutable|string $date): int

Returns the minute of a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4Dates::getMinute($date); // 30

Returns int — The minute as an integer from 0 to 59

See also

• \Phuture\Coherence\Dates::getHour()
• \Phuture\Coherence\Dates::getSecond()

#getMonth()

public static function getMonth(DateTimeImmutable|string $date): int

Returns the month number of a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4Dates::getMonth($date); // 4

Returns int — The month as an integer from 1 (January) to 12 (December)

See also

• \Phuture\Coherence\Dates::getYear()
• \Phuture\Coherence\Dates::getDay()

#getSecond()

public static function getSecond(DateTimeImmutable|string $date): int

Returns the second of a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:45');
4Dates::getSecond($date); // 45

Returns int — The second as an integer from 0 to 59

See also

• \Phuture\Coherence\Dates::getHour()
• \Phuture\Coherence\Dates::getMinute()

#getTimezone()

public static function getTimezone(DateTimeImmutable|string $date): string

Returns the timezone identifier of a date/time value.

Extracts the name of the timezone that is associated with the given date, such as 'America/New_York' or 'UTC'.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::now('Asia/Tokyo');
4$tz = Dates::getTimezone($date); // 'Asia/Tokyo'

Returns string — The timezone identifier string (e.g. 'Europe/Paris')

See also

• \Phuture\Coherence\Dates::toTimezone()

#getWeekOfYear()

public static function getWeekOfYear(DateTimeImmutable|string $date): int

Returns the ISO 8601 week number of the year for a date/time value.

Weeks start on Monday. The first week of the year is the week containing the year's first Thursday (ISO 8601 definition).

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-01-01');
4Dates::getWeekOfYear($date); // 1

Returns int — The ISO 8601 week number from 1 to 53

See also

• \Phuture\Coherence\Dates::getDayOfYear()

#getYear()

public static function getYear(DateTimeImmutable|string $date): int

Returns the four-digit year of a date/time value.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4Dates::getYear($date); // 2026

Returns int — The year as a four-digit integer (e.g. 2026)

See also

• \Phuture\Coherence\Dates::getMonth()
• \Phuture\Coherence\Dates::getDay()

#isAfter()

public static function isAfter(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether a date/time value is after another.

Returns true if the first date comes later in time than the second date. Both dates are compared as absolute points in time, regardless of timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$later = Dates::parse('2026-12-31');
4$earlier = Dates::parse('2026-01-01');
5Dates::isAfter($later, $earlier); // true

Returns bool — Returns true if $date is after $comparedTo

See also

• \Phuture\Coherence\Dates::isBefore()
• \Phuture\Coherence\Dates::equals()

#isBefore()

public static function isBefore(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether a date/time value is before another.

Returns true if the first date comes earlier in time than the second date. Both dates are compared as absolute points in time, regardless of timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$earlier = Dates::parse('2026-01-01');
4$later = Dates::parse('2026-12-31');
5Dates::isBefore($earlier, $later); // true
6Dates::isBefore($later, $earlier); // false

Returns bool — Returns true if $date is before $comparedTo

See also

• \Phuture\Coherence\Dates::isAfter()
• \Phuture\Coherence\Dates::equals()

#isBusinessDay()

public static function isBusinessDay(DateTimeImmutable|string $date, ?array $holidays = null): bool

Checks whether a date/time value falls on a business day.

A business day is a weekday (Monday through Friday) that is not a holiday. When no holiday list is given, the static Dates::$holidays property is used to exclude common holidays. Pass a custom list to override the defaults.

Example:

 1use Phuture\Coherence\Dates;
 2
 3// Uses default holidays (Jan 1, Dec 25, Dec 31)
 4Dates::isBusinessDay('2026-01-01'); // false (holiday)
 5Dates::isBusinessDay('2026-01-02'); // true (Friday, not a holiday)
 6Dates::isBusinessDay('2026-04-18'); // false (Saturday)
 7
 8// Custom holidays override the defaults
 9$custom = [['month' => 7, 'day' => 4]];
10Dates::isBusinessDay('2026-07-04', $custom); // false (holiday)

Returns bool — Returns true if the date is a weekday and not a holiday

See also

• \Phuture\Coherence\Dates::$holidays
• \Phuture\Coherence\Dates::isWeekday()
• \Phuture\Coherence\Dates::isWeekend()
• \Phuture\Coherence\Dates::isHoliday()

#isFuture()

public static function isFuture(DateTimeImmutable|string $date): bool

Checks whether a date/time value is in the future.

Returns true if the given date/time is strictly after the current moment.

Example:

1use Phuture\Coherence\Dates;
2
3$future = Dates::parse('2030-01-01');
4$past = Dates::parse('2020-01-01');
5Dates::isFuture($future); // true
6Dates::isFuture($past); // false

Returns bool — Returns true if the date is after the current moment

See also

• \Phuture\Coherence\Dates::isPast()

#isHoliday()

public static function isHoliday(DateTimeImmutable|string $date, ?array $holidays = null): bool

Checks whether a date/time value falls on a holiday.

Compares the month and day of the given date against a list of fixed-date holidays. Each holiday is defined as an associative array with month (1–12) and day (1–31) keys. The year is not considered, so the same holiday definition matches every year.

When no holiday list is given, the static Dates::$holidays property is used. That property ships with three common holidays: New Year's Day (January 1), Christmas Day (December 25), and New Year's Eve (December 31). You can override it globally or pass a custom list to this method.

Example:

 1use Phuture\Coherence\Dates;
 2
 3// Uses the default holidays (Jan 1, Dec 25, Dec 31)
 4Dates::isHoliday('2026-01-01'); // true
 5Dates::isHoliday('2026-12-25'); // true
 6Dates::isHoliday('2026-12-31'); // true
 7Dates::isHoliday('2026-03-15'); // false
 8
 9// Custom holidays override the defaults
10$custom = [['month' => 7, 'day' => 4]];
11Dates::isHoliday('2026-07-04', $custom); // true

Returns bool — Returns true if the date matches any holiday in the list

See also

• \Phuture\Coherence\Dates::$holidays
• \Phuture\Coherence\Dates::isBusinessDay()
• \Phuture\Coherence\Dates::isWeekend()

#isLeapYear()

public static function isLeapYear(DateTimeImmutable|string $date): bool

Checks whether the year of a date/time value is a leap year.

A leap year has 366 days. It occurs when the year is divisible by 4, except for years divisible by 100, which must also be divisible by 400.

Example:

1use Phuture\Coherence\Dates;
2
3Dates::isLeapYear(Dates::parse('2024-01-01')); // true
4Dates::isLeapYear(Dates::parse('2026-01-01')); // false

Returns bool — Returns true if the year is a leap year

See also

• \Phuture\Coherence\Dates::getDaysInMonth()

#isPast()

public static function isPast(DateTimeImmutable|string $date): bool

Checks whether a date/time value is in the past.

Returns true if the given date/time is strictly before the current moment.

Example:

1use Phuture\Coherence\Dates;
2
3$past = Dates::parse('2020-01-01');
4$future = Dates::parse('2030-01-01');
5Dates::isPast($past); // true
6Dates::isPast($future); // false

Returns bool — Returns true if the date is before the current moment

See also

• \Phuture\Coherence\Dates::isFuture()

#isSameDay()

public static function isSameDay(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether two date/time values fall on the same calendar day.

Compares only the year, month, and day. The time portions and timezones are ignored in this comparison. The comparison is done in each date's own timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$morning = Dates::parse('2026-04-21 08:00:00');
4$evening = Dates::parse('2026-04-21 22:00:00');
5$tomorrow = Dates::parse('2026-04-22 08:00:00');
6Dates::isSameDay($morning, $evening); // true
7Dates::isSameDay($morning, $tomorrow); // false

Returns bool — Returns true if both values fall on the same calendar day

See also

• \Phuture\Coherence\Dates::isSameMonth()
• \Phuture\Coherence\Dates::isSameYear()

#isSameMonth()

public static function isSameMonth(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether two date/time values fall in the same calendar month and year.

Compares the year and month only. The day, time, and timezone are ignored.

Example:

1use Phuture\Coherence\Dates;
2
3$first = Dates::parse('2026-04-01');
4$last = Dates::parse('2026-04-30');
5$next = Dates::parse('2026-05-01');
6Dates::isSameMonth($first, $last); // true
7Dates::isSameMonth($first, $next); // false

Returns bool — Returns true if both values fall in the same calendar month and year

See also

• \Phuture\Coherence\Dates::isSameDay()
• \Phuture\Coherence\Dates::isSameYear()

#isSameYear()

public static function isSameYear(DateTimeImmutable|string $date, DateTimeImmutable|string $comparedTo): bool

Checks whether two date/time values fall in the same calendar year.

Compares only the year. Month, day, time, and timezone are ignored.

Example:

1use Phuture\Coherence\Dates;
2
3$jan = Dates::parse('2026-01-01');
4$dec = Dates::parse('2026-12-31');
5$ny = Dates::parse('2027-01-01');
6Dates::isSameYear($jan, $dec); // true
7Dates::isSameYear($jan, $ny); // false

Returns bool — Returns true if both values fall in the same calendar year

See also

• \Phuture\Coherence\Dates::isSameDay()
• \Phuture\Coherence\Dates::isSameMonth()

#isToday()

public static function isToday(DateTimeImmutable|string $date): bool

Checks whether a date/time value falls on today's date.

Compares only the calendar date (year, month, day) in the date's own timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$today = Dates::now();
4$yesterday = Dates::removeSeconds($today, 86400);
5Dates::isToday($today); // true
6Dates::isToday($yesterday); // false

Returns bool — Returns true if the date falls on today's calendar date

See also

• \Phuture\Coherence\Dates::isYesterday()
• \Phuture\Coherence\Dates::isTomorrow()

#isTomorrow()

public static function isTomorrow(DateTimeImmutable|string $date): bool

Checks whether a date/time value falls on tomorrow's date.

Compares only the calendar date (year, month, day) in the date's own timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$tomorrow = Dates::addSeconds(Dates::now(), 86400);
4Dates::isTomorrow($tomorrow); // true

Returns bool — Returns true if the date falls on tomorrow's calendar date

See also

• \Phuture\Coherence\Dates::isToday()
• \Phuture\Coherence\Dates::isYesterday()

#isWeekday()

public static function isWeekday(DateTimeImmutable|string $date): bool

Checks whether a date/time value falls on a weekday (Monday through Friday).

Example:

1use Phuture\Coherence\Dates;
2
3$tuesday = Dates::parse('2026-04-21'); // Tuesday
4$saturday = Dates::parse('2026-04-18'); // Saturday
5Dates::isWeekday($tuesday); // true
6Dates::isWeekday($saturday); // false

Returns bool — Returns true if the date falls on Monday through Friday

See also

• \Phuture\Coherence\Dates::isWeekend()
• \Phuture\Coherence\Dates::getDayOfWeek()

#isWeekend()

public static function isWeekend(DateTimeImmutable|string $date): bool

Checks whether a date/time value falls on a weekend (Saturday or Sunday).

Example:

1use Phuture\Coherence\Dates;
2
3$saturday = Dates::parse('2026-04-18'); // Saturday
4$tuesday = Dates::parse('2026-04-21'); // Tuesday
5Dates::isWeekend($saturday); // true
6Dates::isWeekend($tuesday); // false

Returns bool — Returns true if the date falls on a Saturday or Sunday

See also

• \Phuture\Coherence\Dates::isWeekday()
• \Phuture\Coherence\Dates::getDayOfWeek()

#isYesterday()

public static function isYesterday(DateTimeImmutable|string $date): bool

Checks whether a date/time value falls on yesterday's date.

Compares only the calendar date (year, month, day) in the date's own timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$yesterday = Dates::removeSeconds(Dates::now(), 86400);
4Dates::isYesterday($yesterday); // true

Returns bool — Returns true if the date falls on yesterday's calendar date

See also

• \Phuture\Coherence\Dates::isToday()
• \Phuture\Coherence\Dates::isTomorrow()

#now()

public static function now(?string $timezone = null): DateTimeImmutable

Returns the current date and time.

Creates a new date/time value representing the exact moment this method is called. When no timezone is given, the system's default timezone is used.

Example:

1use Phuture\Coherence\Dates;
2
3$now = Dates::now(); // e.g. 2026-04-21 14:30:00 UTC
4$nowInTokyo = Dates::now('Asia/Tokyo'); // same moment, Tokyo time

Returns DateTimeImmutable — The current date and time in the requested timezone

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is invalid

See also

• \Phuture\Coherence\Dates::create()
• \Phuture\Coherence\Dates::parse()

#of()

public static function of(DateTimeImmutable|string $date, ?string $timezone = null): Type\Dates

Returns a fluent wrapper around a date/time value for chainable operations.

This is the recommended way to work with multiple operations on a single date. Pass either a DateTimeImmutable instance or a date string. When a string is provided, it is parsed using Dates::parse().

Example:

1use Phuture\Coherence\Dates;
2
3$result = Dates::of('2026-04-21 14:30:00')
4    ->addDays(10)
5    ->startOfDay()
6    ->get();
7// DateTimeImmutable for '2026-05-01 00:00:00'

Returns \Phuture\Coherence\Type\Dates — A fluent wrapper that enables method chaining

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the string cannot be parsed or the timezone is invalid

#parse()

public static function parse(string $dateString, ?string $timezone = null): DateTimeImmutable

Parses a date/time string into a DateTimeImmutable value.

Accepts any date/time string that PHP's DateTimeImmutable constructor understands, such as '2026-04-21', 'next Monday', 'yesterday', or '+2 days'.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-12-25');
4$date = Dates::parse('next Friday', 'America/New_York');
5$date = Dates::parse('2026-04-21 14:30:00', 'Europe/Berlin');

Returns DateTimeImmutable — The parsed date and time value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is invalid or the date string cannot be parsed

See also

• \Phuture\Coherence\Dates::fromFormat()
• \Phuture\Coherence\Dates::fromTimestamp()

#removeDays()

public static function removeDays(DateTimeImmutable|string $date, int $days): DateTimeImmutable

Removes a number of days from a date/time value.

Returns a new date/time value that is the given number of days earlier than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::removeDays($date, 5); // '2026-04-16'

Returns DateTimeImmutable — A new date/time value with the days removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $days is negative

See also

• \Phuture\Coherence\Dates::addDays()

#removeHours()

public static function removeHours(DateTimeImmutable|string $date, int $hours): DateTimeImmutable

Removes a number of hours from a date/time value.

Returns a new date/time value that is the given number of hours earlier than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::removeHours($date, 2); // '2026-04-21 12:30:00'

Returns DateTimeImmutable — A new date/time value with the hours removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $hours is negative

See also

• \Phuture\Coherence\Dates::addHours()

#removeMinutes()

public static function removeMinutes(DateTimeImmutable|string $date, int $minutes): DateTimeImmutable

Removes a number of minutes from a date/time value.

Returns a new date/time value that is the given number of minutes earlier than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::removeMinutes($date, 15); // '2026-04-21 14:15:00'

Returns DateTimeImmutable — A new date/time value with the minutes removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $minutes is negative

See also

• \Phuture\Coherence\Dates::addMinutes()

#removeMonths()

public static function removeMonths(DateTimeImmutable|string $date, int $months): DateTimeImmutable

Removes a number of months from a date/time value.

Returns a new date/time value that is the given number of months earlier than the original. When the resulting day does not exist in the target month, PHP overflows to the next month.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-06-15');
4$result = Dates::removeMonths($date, 2); // '2026-04-15'

Returns DateTimeImmutable — A new date/time value with the months removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $months is negative

See also

• \Phuture\Coherence\Dates::addMonths()

#removeSeconds()

public static function removeSeconds(DateTimeImmutable|string $date, int $seconds): DateTimeImmutable

Removes a number of seconds from a date/time value.

Returns a new date/time value that is the given number of seconds earlier than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::removeSeconds($date, 30); // '2026-04-21 14:29:30'

Returns DateTimeImmutable — A new date/time value with the seconds removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $seconds is negative

See also

• \Phuture\Coherence\Dates::addSeconds()

#removeWeeks()

public static function removeWeeks(DateTimeImmutable|string $date, int $weeks): DateTimeImmutable

Removes a number of weeks from a date/time value.

Returns a new date/time value that is the given number of weeks earlier than the original. One week equals exactly 7 days.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::removeWeeks($date, 1); // '2026-04-14'

Returns DateTimeImmutable — A new date/time value with the weeks removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $weeks is negative

See also

• \Phuture\Coherence\Dates::addWeeks()

#removeYears()

public static function removeYears(DateTimeImmutable|string $date, int $years): DateTimeImmutable

Removes a number of years from a date/time value.

Returns a new date/time value that is the given number of years earlier than the original. The original value is never modified.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21');
4$result = Dates::removeYears($date, 10); // '2016-04-21'

Returns DateTimeImmutable — A new date/time value with the years removed

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When $years is negative

See also

• \Phuture\Coherence\Dates::addYears()

#startOfDay()

public static function startOfDay(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the very start of its day (00:00:00).

Keeps the same date and timezone but resets the time to midnight.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:45');
4$result = Dates::startOfDay($date); // '2026-04-21 00:00:00'

Returns DateTimeImmutable — A new date/time value at midnight on the same calendar day

See also

• \Phuture\Coherence\Dates::endOfDay()

#startOfMonth()

public static function startOfMonth(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the first day of the same month at midnight.

Resets the day to 1 and the time to 00:00:00 while preserving the year and month.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4$result = Dates::startOfMonth($date); // '2026-04-01 00:00:00'

Returns DateTimeImmutable — A new date/time value at the first day of the month at 00:00:00

See also

• \Phuture\Coherence\Dates::endOfMonth()

#startOfWeek()

public static function startOfWeek(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to the Monday of the same ISO week at midnight.

The ISO week starts on Monday. The time is reset to 00:00:00.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21'); // Tuesday
4$result = Dates::startOfWeek($date); // '2026-04-20 00:00:00' (Monday)

Returns DateTimeImmutable — A new date/time value at Monday 00:00:00 of the same week

See also

• \Phuture\Coherence\Dates::endOfWeek()

#startOfYear()

public static function startOfYear(DateTimeImmutable|string $date): DateTimeImmutable

Returns a new date/time value set to January 1st of the same year at midnight.

Resets the month and day to January 1 and the time to 00:00:00.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-09-15');
4$result = Dates::startOfYear($date); // '2026-01-01 00:00:00'

Returns DateTimeImmutable — A new date/time value at January 1st of the same year at 00:00:00

See also

• \Phuture\Coherence\Dates::endOfYear()

#toDate()

public static function toDate(DateTimeImmutable|string $date): string

Returns the date portion of a date/time value as a string in Y-m-d format.

Extracts only the year, month, and day from the given date/time value, dropping any time information.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4Dates::toDate($date); // '2026-04-21'

Returns string — The date portion formatted as 'Y-m-d' (e.g. '2026-04-21')

See also

• \Phuture\Coherence\Dates::toTime()
• \Phuture\Coherence\Dates::toDateTime()

#toDateTime()

public static function toDateTime(DateTimeImmutable|string $date): string

Returns a date/time value as a combined date and time string.

Formats the date/time as a human-readable string containing both the date and time components separated by a space.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4Dates::toDateTime($date); // '2026-04-21 14:30:00'

Returns string — The date and time formatted as 'Y-m-d H:i:s' (e.g. '2026-04-21 14:30:00')

See also

• \Phuture\Coherence\Dates::toDate()
• \Phuture\Coherence\Dates::toTime()

#toIso8601()

public static function toIso8601(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an ISO 8601 string.

ISO 8601 is an international standard for representing dates and times. The output includes timezone offset information, making it ideal for data exchange between systems (APIs, JSON payloads, etc.).

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'America/New_York');
4Dates::toIso8601($date); // '2026-04-21T14:30:00-04:00'

Returns string — The date and time formatted according to ISO 8601 (e.g. '2026-04-21T14:30:00+00:00')

See also

• \Phuture\Coherence\Dates::toRfc2822()

#toRelative()

public static function toRelative(DateTimeImmutable|string $date, DateTimeImmutable|string|null $comparedTo = null): string

Returns a human-readable string describing how far a date is from a reference point.

Produces a relative time string like '2 days ago', 'in 3 hours', or 'just now'. The comparison point defaults to the current moment. The output automatically picks the largest whole unit that fits (seconds, minutes, hours, days, weeks, months, or years) and uses singular or plural form.

Output format for past dates: '{n} {unit} ago' (e.g. '5 minutes ago') Output format for future dates: 'in {n} {unit}' (e.g. 'in 2 days') Output for very recent dates: 'just now'

Example:

1use Phuture\Coherence\Dates;
2
3$ref = Dates::parse('2026-04-21 12:00:00', 'UTC');
4
5Dates::toRelative('2026-04-21 11:55:00', $ref); // '5 minutes ago'
6Dates::toRelative('2026-04-21 12:45:00', $ref); // 'in 45 minutes'
7Dates::toRelative('2026-04-19 12:00:00', $ref); // '2 days ago'
8Dates::toRelative('2026-04-21 12:00:30', $ref); // 'just now'

Returns string — A human-readable relative time string

See also

• \Phuture\Coherence\Dates::fromRelative()

#toRfc1036()

public static function toRfc1036(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 1036 string.

RFC 1036 is the standard format used in Usenet news messages (NNTP). It produces a string like "Tue, 21 Apr 26 14:30:00 +0000" with a two-digit year, similar to RFC 822 but used specifically in news article headers.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toRfc1036($date); // 'Tue, 21 Apr 26 14:30:00 +0000'

Returns string — The date and time formatted according to RFC 1036

See also

• \Phuture\Coherence\Dates::toRfc2822()

#toRfc1123()

public static function toRfc1123(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 1123 string.

RFC 1123 is the standard format for HTTP date headers. It produces a string like "Tue, 21 Apr 2026 14:30:00 +0000" with a four-digit year, essentially the same as RFC 2822 but requiring a four-digit year.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toRfc1123($date); // 'Tue, 21 Apr 2026 14:30:00 +0000'

Returns string — The date and time formatted according to RFC 1123

See also

• \Phuture\Coherence\Dates::toRfc2822()

#toRfc2822()

public static function toRfc2822(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 2822 string.

RFC 2822 is the standard format used in email headers and HTTP dates. The output always includes the three-letter day name, day of the month, three-letter month abbreviation, four-digit year, time, and timezone offset.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toRfc2822($date); // 'Tue, 21 Apr 2026 14:30:00 +0000'

Returns string — The date and time formatted according to RFC 2822

See also

• \Phuture\Coherence\Dates::toIso8601()

#toRfc7231()

public static function toRfc7231(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 7231 string.

RFC 7231 is the current standard for HTTP/1.1 date headers. It produces a string like "Tue, 21 Apr 2026 14:30:00 GMT" using the preferred IMF-fixdate format with "GMT" as the fixed timezone indicator. The input date is automatically converted to GMT before formatting.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'America/New_York');
4Dates::toRfc7231($date); // 'Tue, 21 Apr 2026 18:30:00 GMT'

Returns string — The date and time formatted according to RFC 7231 (IMF-fixdate)

See also

• \Phuture\Coherence\Dates::toRfc1123()

#toRfc822()

public static function toRfc822(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 822 string.

RFC 822 is the original standard for date and time in email messages. It produces a string like "Tue, 21 Apr 26 14:30:00 +0000" with a two-digit year. For most modern use cases, RFC 2822 (four-digit year) is preferred.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toRfc822($date); // 'Tue, 21 Apr 26 14:30:00 +0000'

Returns string — The date and time formatted according to RFC 822

See also

• \Phuture\Coherence\Dates::toRfc2822()

#toRfc850()

public static function toRfc850(DateTimeImmutable|string $date): string

Returns a date/time value formatted as an RFC 850 string.

RFC 850 is a format used in some older systems and protocols. It produces a string like "Tuesday, 21-Apr-26 14:30:00 UTC" with the full day name and a two-digit year.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toRfc850($date); // 'Tuesday, 21-Apr-26 14:30:00 UTC'

Returns string — The date and time formatted according to RFC 850

See also

• \Phuture\Coherence\Dates::toRfc2822()

#toTime()

public static function toTime(DateTimeImmutable|string $date): string

Returns the time portion of a date/time value as a string in H:i:s format.

Extracts only the hour, minute, and second from the given date/time value, dropping any date information.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00');
4Dates::toTime($date); // '14:30:00'

Returns string — The time portion formatted as 'H:i:s' (e.g. '14:30:00')

See also

• \Phuture\Coherence\Dates::toDate()
• \Phuture\Coherence\Dates::toDateTime()

#toTimestamp()

public static function toTimestamp(DateTimeImmutable|string $date): int

The Unix timestamp is the number of seconds elapsed since 1 January 1970 00:00:00 UTC, regardless of timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 00:00:00', 'UTC');
4Dates::toTimestamp($date); // 1745193600

Returns int — The number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC)

See also

• \Phuture\Coherence\Dates::fromTimestamp()

#toTimezone()

public static function toTimezone(DateTimeImmutable|string $date, string $timezone): DateTimeImmutable

Converts a date/time value to a different timezone.

The underlying point in time remains exactly the same — only the timezone context used to display it changes. Useful when you need to present a UTC timestamp in a user's local timezone.

Example:

1use Phuture\Coherence\Dates;
2
3$utc = Dates::parse('2026-04-21 12:00:00', 'UTC');
4$ny = Dates::toTimezone($utc, 'America/New_York');
5// $ny displays as '2026-04-21 08:00:00' but represents the same moment

Returns DateTimeImmutable — A new date/time value in the requested timezone

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is invalid

See also

• \Phuture\Coherence\Dates::getTimezone()

#toW3c()

public static function toW3c(DateTimeImmutable|string $date): string

Returns a date/time value formatted as a W3C string.

The W3C format is a simplified subset of ISO 8601 commonly used in HTML documents, XML schemas, and web APIs. It produces a string like "2026-04-21T14:30:00+00:00" with the timezone offset included.

Example:

1use Phuture\Coherence\Dates;
2
3$date = Dates::parse('2026-04-21 14:30:00', 'UTC');
4Dates::toW3c($date); // '2026-04-21T14:30:00+00:00'

Returns string — The date and time formatted according to the W3C standard

See also

• \Phuture\Coherence\Dates::toIso8601()

#buildTimezone()

private static function buildTimezone(?string $timezone): DateTimeZone

Builds a DateTimeZone from a timezone string, or returns the system default timezone.

Returns DateTimeZone — The resolved timezone object

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the timezone string is not a valid identifier

#convertDayJsFormatToPhp()

private static function convertDayJsFormatToPhp(string $dayJsFormat): string

Converts a day.js-style format string to PHP native date() format characters.

Returns string — The equivalent format string using PHP date() characters

#formatRelativeString()

private static function formatRelativeString(int $value, string $unit, bool $isFuture): string

Formats a relative time string with proper singular/plural and direction.

Returns string — The formatted relative string (e.g. 'in 2 days', '5 hours ago')

#isDayJsFormat()

private static function isDayJsFormat(string $format): bool

Determines whether a format string contains day.js-style multi-character tokens.

Returns bool — Returns true if the format contains day.js tokens or bracket escapes

#normalizeRelativeExpression()

private static function normalizeRelativeExpression(string $expression): string

#relativeThresholds()

private static function relativeThresholds(): array

Returns the ordered threshold definitions used by toRelative.

Each entry maps a time unit to its divisor (in seconds) and the minimum number of seconds that must have elapsed before that unit is chosen. Ordered from largest unit to smallest so the first match wins.

Returns array<int, — array{unit: string, divisor: int, minimum: int}>

#resolveDate()

private static function resolveDate(DateTimeImmutable|string $date): DateTimeImmutable

Resolves a DateTimeImmutable|string argument to a DateTimeImmutable instance.

Returns DateTimeImmutable — The resolved date/time value

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the string cannot be parsed

#resolveRelativeBaseDate()

private static function resolveRelativeBaseDate(DateTimeImmutable|string|null $relativeTo, ?string $timezone): DateTimeImmutable

Resolves the base date for fromRelative from the $relativeTo parameter.

Returns DateTimeImmutable — The resolved reference date