Class Date

Extends the Date class provided by Chronos.

Adds handy methods and locale-aware formatting helpers.

Namespace: Cake\I18n

Constants

string

DEFAULT_TO_STRING_FORMAT ¶
```
'Y-m-d'
```
Default format to use for __toString method when type juggling occurs.

Property Summary

$_jsonEncodeFormat protected static

Closure|string|int

The format to use when converting this object to JSON.
$_toStringFormat protected static

string|int

The format to use when formatting a time using Cake\I18n\Date::i18nFormat() and __toString.
$age public @property-read

int

does a diffInYears() with default parameters
$day public @property-read

int<1, 31>
$dayOfWeek public @property-read

int<1, 7>

1 (for Monday) through 7 (for Sunday)
$dayOfYear public @property-read

int<0, 365>

0 through 365
$days protected static

array

Names of days of the week.
$daysInMonth public @property-read

int<1, 31>

number of days in the given month
$diffFormatter protected static

Cake\Chronos\DifferenceFormatterInterface|null

Instance of the diff formatting object.
$formatters protected static

array<string,IntlDateFormatter>

In-memory cache of date formatters
$half public @property-read

int<1, 2>

the half of the year, with 1 for months Jan...Jun and 2 for Jul...Dec.
$lastErrors protected static

array|false

Errors from last time createFromFormat() was called.
$month public @property-read

int<1, 12>
$native protected

DateTimeImmutable
$niceFormat public static

string|int

The format to use when formatting a time using Cake\I18n\Date::nice()
$quarter public @property-read

int<1, 4>

the quarter of this instance, 1 - 4
$toStringFormat protected static

string

Format to use for __toString method when type juggling occurs.
$weekOfMonth public @property-read

int<1, 5>

1 through 5
$weekOfYear public @property-read

int<1, 53>

ISO-8601 week number of year, weeks starting on Monday
$wordAccuracy public static

array<string>

The format to use when formatting a time using Date::timeAgoInWords() and the difference is less than Date::$wordEnd
$wordEnd public static

string

The end of relative time telling
$wordFormat public static

string|int

The format to use when formatting a time using Cake\I18n\Date::timeAgoInWords() and the difference is more than Cake\I18n\Date::$wordEnd
$year public @property-read

int
$yearIso public @property-read

int

Method Summary

__construct() public

Create a new Immutable Date instance.
__debugInfo() public

Return properties for debugging.
__get() public

Get a part of the object
__isset() public

Check if an attribute exists on the object
__toString() public

Returns a formatted string specified by setToStringFormat() or the default DEFAULT_TO_STRING_FORMAT format.
_formatObject() protected

Returns a translated and localized date string. Implements what IntlDateFormatter::formatObject() is in PHP 5.5+
_parseDateTime() protected static

Returns a new Time object after parsing the provided time string based on the passed or configured date time format. This method is locale dependent, Any string that is passed to this function will be interpreted as a locale dependent string.
add() public

Add an Interval to a Date
addDays() public

Add days to the instance. Positive $value travels forward while negative $value travels into the past.
addMonths() public

Add months to the instance. Positive $value travels forward while negative $value travels into the past.
addMonthsWithOverflow() public

Add months with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.
addWeekdays() public

Add weekdays to the instance. Positive $value travels forward while negative $value travels into the past.
addWeeks() public

Add weeks to the instance. Positive $value travels forward while negative $value travels into the past.
addYears() public

Add years to the instance. Positive $value travel forward while negative $value travel into the past.
addYearsWithOverflow() public

Add years with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.
between() public

Determines if the instance is between two others
closest() public

Get the closest date from the instance.
create() public static

Create an instance from a specific date.
createFromArray() public static

Creates an instance from an array of date values.
createFromFormat() public static

Create an instance from a specific format
createNative() protected

Initializes the PHP DateTimeImmutable object.
day() public

Set the instance's day
diff() public

Returns the difference between this instance and target.
diffFiltered() public

Get the difference by the given interval using a filter callable
diffForHumans() public

Get the difference in a human readable format.
diffFormatter() public static

Get the difference formatter instance.
diffInDays() public

Get the difference in days
diffInDaysFiltered() public

Get the difference in days using a filter callable
diffInMonths() public

Get the difference in months
diffInWeekdays() public

Get the difference in weekdays
diffInWeekendDays() public

Get the difference in weekend days using a filter
diffInWeeks() public

Get the difference in weeks
diffInYears() public

Get the difference in years
endOfCentury() public

Resets the date to end of the century and time to 23:59:59
endOfDecade() public

Resets the date to end of the decade
endOfMonth() public

Resets the date to end of the month
endOfWeek() public

Resets the date to end of week (defined in $weekEndsAt) and time to 23:59:59
endOfYear() public

Resets the date to end of the year
equals() public

Determines if the instance is equal to another
farthest() public

Get the farthest date from the instance.
firstOfMonth() public

Modify to the first occurrence of a given day of the week in the current month. If no dayOfWeek is provided, modify to the first day of the current month. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
firstOfQuarter() public

Modify to the first occurrence of a given day of the week in the current quarter. If no dayOfWeek is provided, modify to the first day of the current quarter. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
firstOfYear() public

Modify to the first occurrence of a given day of the week in the current year. If no dayOfWeek is provided, modify to the first day of the current year. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
format() public

Returns formatted date string according to DateTimeImmutable::format().
getLastErrors() public static

Returns parse warnings and errors from the last createFromFormat() call.
greaterThan() public

Determines if the instance is greater (after) than another
greaterThanOrEquals() public

Determines if the instance is greater (after) than or equal to another
i18nFormat() public

Returns a formatted string for this time object using the preferred format and language for the specified locale.
isFirstHalf() public

Determines if the instance is within the first half of year
isFriday() public

Checks if this day is a Friday.
isFuture() public

Determines if the instance is in the future, ie. greater (after) than now
isLastMonth() public

Determines if the instance is within the last month
isLastWeek() public

Determines if the instance is within the last week
isLastYear() public

Determines if the instance is within the last year
isLeapYear() public

Determines if the instance is a leap year
isMonday() public

Checks if this day is a Monday.
isNextMonth() public

Determines if the instance is within the next month
isNextWeek() public

Determines if the instance is within the next week
isNextYear() public

Determines if the instance is within the next year
isPast() public

Determines if the instance is in the past, ie. less (before) than now
isSaturday() public

Checks if this day is a Saturday.
isSecondHalf() public

Determines if the instance is within the second half of year
isSunday() public

Checks if this day is a Sunday.
isThursday() public

Checks if this day is a Thursday.
isToday() public

Determines if the instance is today
isTomorrow() public

Determines if the instance is tomorrow
isTuesday() public

Checks if this day is a Tuesday.
isWednesday() public

Checks if this day is a Wednesday.
isWeekday() public

Determines if the instance is a weekday
isWeekend() public

Determines if the instance is a weekend day
isWithinNext() public

Returns true this instance will happen within the specified interval
isYesterday() public

Determines if the instance is yesterday
jsonSerialize() public

Returns a string that should be serialized when converting this object to JSON
lastOfMonth() public

Modify to the last occurrence of a given day of the week in the current month. If no dayOfWeek is provided, modify to the last day of the current month. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
lastOfQuarter() public

Modify to the last occurrence of a given day of the week in the current quarter. If no dayOfWeek is provided, modify to the last day of the current quarter. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
lastOfYear() public

Modify to the last occurrence of a given day of the week in the current year. If no dayOfWeek is provided, modify to the last day of the current year. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
lessThan() public

Determines if the instance is less (before) than another
lessThanOrEquals() public

Determines if the instance is less (before) or equal to another
modify() public

Creates a new instance with date modified according to DateTimeImmutable::modifier().
month() public

Set the instance's month
next() public

Modify to the next occurrence of a given day of the week. If no dayOfWeek is provided, modify to the next occurrence of the current day of the week. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
nice() public

Returns a nicely formatted date string for this object.
notEquals() public

Determines if the instance is not equal to another
now() public static

Get today's date.
nthOfMonth() public

Modify to the given occurrence of a given day of the week in the current month. If the calculated occurrence is outside the scope of the current month, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
nthOfQuarter() public

Modify to the given occurrence of a given day of the week in the current quarter. If the calculated occurrence is outside the scope of the current quarter, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
nthOfYear() public

Modify to the given occurrence of a given day of the week in the current year. If the calculated occurrence is outside the scope of the current year, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
parse() public static

Create an instance from a string. This is an alias for the constructor that allows better fluent syntax as it allows you to do Chronos::parse('Monday next week')->fn() rather than (new Chronos('Monday next week'))->fn()
parseDate() public static

Returns a new Date object after parsing the provided $date string based on the passed or configured format. This method is locale dependent, Any string that is passed to this function will be interpreted as a locale dependent string.
previous() public

Modify to the previous occurrence of a given day of the week. If no dayOfWeek is provided, modify to the previous occurrence of the current day of the week. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.
resetToStringFormat() public static

Resets the __toString() format to DEFAULT_TO_STRING_FORMAT.
setDate() public

Sets the date.
setISODate() public

Sets the date according to the ISO 8601 standard
setJsonEncodeFormat() public static

Sets the default format used when converting this object to JSON
setToStringFormat() public static

Sets the default format used when type converting instances of this type to string
startOfCentury() public

Resets the date to the first day of the century
startOfDecade() public

Resets the date to the first day of the decade
startOfMonth() public

Resets the date to the first day of the month
startOfWeek() public

Resets the date to the first day of week (defined in $weekStartsAt)
startOfYear() public

Resets the date to the first day of the year
sub() public

Subtract an Interval from a Date.
subDays() public

Remove days from the instance
subMonths() public

Remove months from the instance
subMonthsWithOverflow() public

Add months with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.
subWeekdays() public

Remove weekdays from the instance
subWeeks() public

Remove weeks to the instance
subYears() public

Remove years from the instance.
subYearsWithOverflow() public

Remove years with overflow from the instance
timeAgoInWords() public

Returns either a relative or a formatted absolute date depending on the difference between the current date and this object.
toAtomString() public

Format the instance as ATOM
toCookieString() public

Format the instance as COOKIE
toDateString() public

Format the instance as date
toDateTimeImmutable() public

Returns the date as a DateTimeImmutable instance at midnight.
toDateTimeString() public

Format the instance as date and time
toDayDateTimeString() public

Format the instance with day, date and time
toFormattedDateString() public

Format the instance as a readable date
toIso8601String() public

Format the instance as ISO8601
toNative() public

Returns the date as a DateTimeImmutable instance at midnight.
toQuarter() public

Returns the quarter
toRfc1036String() public

Format the instance as RFC1036
toRfc1123String() public

Format the instance as RFC1123
toRfc2822String() public

Format the instance as RFC2822
toRfc3339String() public

Format the instance as RFC3339
toRfc822String() public

Format the instance as RFC822
toRfc850String() public

Format the instance as RFC850
toRssString() public

Format the instance as RSS
toTimeString() public

Format the instance as time
toUnixString() public

Returns a UNIX timestamp.
toW3cString() public

Format the instance as W3C
toWeek() public

Returns ISO 8601 week number of year, weeks starting on Monday
today() public static

Get today's date.
tomorrow() public static

Get tomorrow's date.
wasWithinLast() public

Returns true this instance happened within the specified interval
year() public

Set the instance's year
yesterday() public static

Get yesterday's date.

Method Detail

__construct() ¶ public

__construct(Cake\Chronos\ChronosDateDateTimeInterface|string $time = 'now', DateTimeZone|string|null $timezone = null)

Create a new Immutable Date instance.

Dates do not have time or timezone components exposed. Internally ChronosDate wraps a PHP DateTimeImmutable but limits modifications to only those that operate on day values.

By default dates will be calculated from the server's default timezone. You can use the timezone parameter to use a different timezone. Timezones are used when parsing relative date expressions like today and yesterday but do not participate in parsing values like 2022-01-01.

Parameters

Cake\Chronos\ChronosDateDateTimeInterface|string $time optional: Fixed or relative time
DateTimeZone|string|null $timezone optional: The time zone used for 'now'

__debugInfo() ¶ public

__debugInfo(): array

Return properties for debugging.

Returns

array

__get() ¶ public

__get(string $name): string|float|int|bool

Get a part of the object

Parameters

string $name: The property name to read.

Returns

string|float|int|bool

Throws

InvalidArgumentException

__isset() ¶ public

__isset(string $name): bool

Check if an attribute exists on the object

Parameters

string $name: The property name to check.

Returns

bool

__toString() ¶ public

__toString(): string

Returns a formatted string specified by setToStringFormat() or the default DEFAULT_TO_STRING_FORMAT format.

Returns

string

_formatObject() ¶ protected

_formatObject(DateTimeInterface $date, array<int>|string $format, string|null $locale): string

Returns a translated and localized date string. Implements what IntlDateFormatter::formatObject() is in PHP 5.5+

Parameters

DateTimeInterface $date: Date.
array<int>|string $format: Format.
string|null $locale: The locale name in which the date should be displayed.

Returns

string

_parseDateTime() ¶ protected static

_parseDateTime(string $time, array<int>|string $format, DateTimeZone|string|null $tz = null): static|null

Returns a new Time object after parsing the provided time string based on the passed or configured date time format. This method is locale dependent, Any string that is passed to this function will be interpreted as a locale dependent string.

Unlike DateTime, the time zone of the returned instance is always converted to $tz (default time zone if null) even if the $time string specified a time zone. This is a limitation of IntlDateFormatter.

If it was impossible to parse the provided time, null will be returned.

Example:

 $time = Time::parseDateTime('10/13/2013 12:54am');
 $time = Time::parseDateTime('13 Oct, 2013 13:54', 'dd MMM, y H:mm');
 $time = Time::parseDateTime('10/10/2015', [IntlDateFormatter::SHORT, IntlDateFormatter::NONE]);

Parameters

string $time: The time string to parse.
array<int>|string $format: Any format accepted by IntlDateFormatter.
DateTimeZone|string|null $tz optional: The timezone for the instance

Returns

static|null

add() ¶ public

add(DateInterval $interval): static

Add an Interval to a Date

Any changes to the time will be ignored and reset to 00:00:00

Parameters

DateInterval $interval: The interval to modify this date by.

Returns

static

addDays() ¶ public

addDays(int $value): static

Add days to the instance. Positive $value travels forward while negative $value travels into the past.

Parameters

int $value: The number of days to add.

Returns

static

addMonths() ¶ public

addMonths(int $value): static

Add months to the instance. Positive $value travels forward while negative $value travels into the past.

When adding or subtracting months, if the resulting time is a date that does not exist, the result of this operation will always be the last day of the intended month.

Example:

 (new Chronos('2015-01-03'))->addMonths(1); // Results in 2015-02-03

(new Chronos('2015-01-31'))->addMonths(1); // Results in 2015-02-28

Parameters

int $value: The number of months to add.

Returns

static

addMonthsWithOverflow() ¶ public

addMonthsWithOverflow(int $value): static

Add months with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.

If the new ChronosDate does not exist, the days overflow into the next month.

Example:

 (new Chronos('2012-01-30'))->addMonthsWithOverflow(1); // Results in 2013-03-01

Parameters

int $value: The number of months to add.

Returns

static

addWeekdays() ¶ public

addWeekdays(int $value): static

Add weekdays to the instance. Positive $value travels forward while negative $value travels into the past.

Parameters

int $value: The number of weekdays to add.

Returns

static

addWeeks() ¶ public

addWeeks(int $value): static

Add weeks to the instance. Positive $value travels forward while negative $value travels into the past.

Parameters

int $value: The number of weeks to add.

Returns

static

addYears() ¶ public

addYears(int $value): static

Add years to the instance. Positive $value travel forward while negative $value travel into the past.

If the new ChronosDate does not exist, the last day of the month is used instead instead of overflowing into the next month.

Example:

 (new Chronos('2015-01-03'))->addYears(1); // Results in 2016-01-03

(new Chronos('2012-02-29'))->addYears(1); // Results in 2013-02-28

Parameters

int $value: The number of years to add.

Returns

static

addYearsWithOverflow() ¶ public

addYearsWithOverflow(int $value): static

Add years with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.

If the new ChronosDate does not exist, the days overflow into the next month.

Example:

 (new Chronos('2012-02-29'))->addYearsWithOverflow(1); // Results in 2013-03-01

Parameters

int $value: The number of years to add.

Returns

static

between() ¶ public

between(Cake\Chronos\ChronosDate $start, Cake\Chronos\ChronosDate $end, bool $equals = true): bool

Determines if the instance is between two others

Parameters

Cake\Chronos\ChronosDate $start: Start of target range
Cake\Chronos\ChronosDate $end: End of target range
bool $equals optional: Whether to include the beginning and end of range

Returns

bool

closest() ¶ public

closest(Cake\Chronos\ChronosDate $first, Cake\Chronos\ChronosDate $second, Cake\Chronos\ChronosDate ...$others): self

Get the closest date from the instance.

Parameters

Cake\Chronos\ChronosDate $first: The instance to compare with.
Cake\Chronos\ChronosDate $second: The instance to compare with.
Cake\Chronos\ChronosDate ...$others: Others instance to compare with.

Returns

self

create() ¶ public static

create(int $year, int $month, int $day): static

Create an instance from a specific date.

Parameters

int $year: The year to create an instance with.
int $month: The month to create an instance with.
int $day: The day to create an instance with.

Returns

static

createFromArray() ¶ public static

createFromArray(array<int|string> $values): static

Creates an instance from an array of date values.

Allowed values:

year
month
day

Parameters

array<int|string> $values: Array of date and time values.

Returns

static

createFromFormat() ¶ public static

createFromFormat(string $format, string $time): static

Create an instance from a specific format

Parameters

string $format: The date() compatible format string.
string $time: The formatted date string to interpret.

Returns

static

Throws

InvalidArgumentException

createNative() ¶ protected

createNative(Cake\Chronos\ChronosDateDateTimeInterface|string $time, DateTimeZone|string|null $timezone): DateTimeImmutable

Initializes the PHP DateTimeImmutable object.

Parameters

Cake\Chronos\ChronosDateDateTimeInterface|string $time: Fixed or relative time
DateTimeZone|string|null $timezone: The time zone used for 'now'

Returns

DateTimeImmutable

day() ¶ public

day(int $value): static

Set the instance's day

Parameters

int $value: The day value.

Returns

static

diff() ¶ public

diff(Cake\Chronos\ChronosDate $target, bool $absolute = false): DateInterval

Returns the difference between this instance and target.

Parameters

Cake\Chronos\ChronosDate $target: Target instance
bool $absolute optional: Whether the interval is forced to be positive

Returns

DateInterval

diffFiltered() ¶ public

diffFiltered(DateInterval $interval, callable $callback, Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true, int $options = 0): int

Get the difference by the given interval using a filter callable

Parameters

DateInterval $interval: An interval to traverse by
callable $callback: The callback to use for filtering.
Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference
int $options optional: DatePeriod options, {@see https://www.php.net/manual/en/class.dateperiod.php}

Returns

int

diffForHumans() ¶ public

diffForHumans(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = false): string

Get the difference in a human readable format.

When comparing a value in the past to default now: 5 months ago

When comparing a value in the future to default now: 5 months from now

When comparing a value in the past to another value: 5 months before

When comparing a value in the future to another value: 5 months after

Parameters

Cake\Chronos\ChronosDate|null $other optional: The datetime to compare with.
bool $absolute optional: removes difference modifiers ago, after, etc

Returns

string

diffFormatter() ¶ public static

diffFormatter(Cake\Chronos\DifferenceFormatterInterface|null $formatter = null): Cake\I18n\RelativeTimeFormatter

Get the difference formatter instance.

Parameters

Cake\Chronos\DifferenceFormatterInterface|null $formatter optional: Difference formatter

Returns

Cake\I18n\RelativeTimeFormatter

diffInDays() ¶ public

diffInDays(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true): int

Get the difference in days

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference

Returns

int

diffInDaysFiltered() ¶ public

diffInDaysFiltered(callable $callback, Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true, int $options = 0): int

Get the difference in days using a filter callable

Parameters

callable $callback: The callback to use for filtering.
Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference
int $options optional: DatePeriod options, {@see https://www.php.net/manual/en/class.dateperiod.php}

Returns

int

diffInMonths() ¶ public

diffInMonths(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true): int

Get the difference in months

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference

Returns

int

diffInWeekdays() ¶ public

diffInWeekdays(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true, int $options = 0): int

Get the difference in weekdays

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference
int $options optional: DatePeriod options, {@see https://www.php.net/manual/en/class.dateperiod.php}

Returns

int

diffInWeekendDays() ¶ public

diffInWeekendDays(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true, int $options = 0): int

Get the difference in weekend days using a filter

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference
int $options optional: DatePeriod options, {@see https://www.php.net/manual/en/class.dateperiod.php}

Returns

int

diffInWeeks() ¶ public

diffInWeeks(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true): int

Get the difference in weeks

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference

Returns

int

diffInYears() ¶ public

diffInYears(Cake\Chronos\ChronosDate|null $other = null, bool $absolute = true): int

Get the difference in years

Parameters

Cake\Chronos\ChronosDate|null $other optional: The instance to difference from.
bool $absolute optional: Get the absolute of the difference

Returns

int

endOfCentury() ¶ public

endOfCentury(): static

Resets the date to end of the century and time to 23:59:59

Returns

static

endOfDecade() ¶ public

endOfDecade(): static

Resets the date to end of the decade

Returns

static

endOfMonth() ¶ public

endOfMonth(): static

Resets the date to end of the month

Returns

static

endOfWeek() ¶ public

endOfWeek(): static

Resets the date to end of week (defined in $weekEndsAt) and time to 23:59:59

Returns

static

endOfYear() ¶ public

endOfYear(): static

Resets the date to end of the year

Returns

static

equals() ¶ public

equals(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is equal to another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

farthest() ¶ public

farthest(Cake\Chronos\ChronosDate $first, Cake\Chronos\ChronosDate $second, Cake\Chronos\ChronosDate ...$others): self

Get the farthest date from the instance.

Parameters

Cake\Chronos\ChronosDate $first: The instance to compare with.
Cake\Chronos\ChronosDate $second: The instance to compare with.
Cake\Chronos\ChronosDate ...$others: Others instance to compare with.

Returns

self

firstOfMonth() ¶ public

firstOfMonth(int|null $dayOfWeek = null): static

Modify to the first occurrence of a given day of the week in the current month. If no dayOfWeek is provided, modify to the first day of the current month. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

firstOfQuarter() ¶ public

firstOfQuarter(int|null $dayOfWeek = null): static

Modify to the first occurrence of a given day of the week in the current quarter. If no dayOfWeek is provided, modify to the first day of the current quarter. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

firstOfYear() ¶ public

firstOfYear(int|null $dayOfWeek = null): static

Modify to the first occurrence of a given day of the week in the current year. If no dayOfWeek is provided, modify to the first day of the current year. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

format() ¶ public

format(string $format): string

Returns formatted date string according to DateTimeImmutable::format().

Parameters

string $format: String format

Returns

string

getLastErrors() ¶ public static

getLastErrors(): array|false

Returns parse warnings and errors from the last createFromFormat() call.

Returns the same data as DateTimeImmutable::getLastErrors().

Returns

array|false

greaterThan() ¶ public

greaterThan(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is greater (after) than another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

greaterThanOrEquals() ¶ public

greaterThanOrEquals(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is greater (after) than or equal to another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

i18nFormat() ¶ public

i18nFormat(string|int|null $format = null, string|null $locale = null): string|int

Returns a formatted string for this time object using the preferred format and language for the specified locale.

It is possible to specify the desired format for the string to be displayed. You can either pass IntlDateFormatter constants as the first argument of this function, or pass a full ICU date formatting string as specified in the following resource: https://unicode-org.github.io/icu/userguide/format_parse/datetime/#datetime-format-syntax.

Examples

$date = new Date('2014-04-20');
$date->i18nFormat(); // outputs '4/20/14' for the en-US locale
$date->i18nFormat(\IntlDateFormatter::FULL); // Use the full date format
$date->i18nFormat('yyyy-MM-dd'); // outputs '2014-04-20'

You can control the default format used through Date::setToStringFormat().

You can read about the available IntlDateFormatter constants at https://secure.php.net/manual/en/class.intldateformatter.php

Should you need to use a different locale for displaying this time object, pass a locale string as the third parameter to this function.

Examples

$date = new Date('2014-04-20');
$time->i18nFormat(null, 'de-DE');
$time->i18nFormat(\IntlDateFormatter::FULL, 'de-DE');

You can control the default locale used through Date::setDefaultLocale(). If empty, the default will be taken from the intl.default_locale ini config.

Parameters

string|int|null $format optional: Format string.
string|null $locale optional: The locale name in which the date should be displayed (e.g. pt-BR)

Returns

string|int

isFirstHalf() ¶ public

isFirstHalf(): bool

Determines if the instance is within the first half of year

Returns

bool

isFriday() ¶ public

isFriday(): bool

Checks if this day is a Friday.

Returns

bool

isFuture() ¶ public

isFuture(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is in the future, ie. greater (after) than now

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isLastMonth() ¶ public

isLastMonth(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the last month

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isLastWeek() ¶ public

isLastWeek(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the last week

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isLastYear() ¶ public

isLastYear(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the last year

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isLeapYear() ¶ public

isLeapYear(): bool

Determines if the instance is a leap year

Returns

bool

isMonday() ¶ public

isMonday(): bool

Checks if this day is a Monday.

Returns

bool

isNextMonth() ¶ public

isNextMonth(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the next month

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isNextWeek() ¶ public

isNextWeek(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the next week

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isNextYear() ¶ public

isNextYear(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is within the next year

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isPast() ¶ public

isPast(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is in the past, ie. less (before) than now

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isSaturday() ¶ public

isSaturday(): bool

Checks if this day is a Saturday.

Returns

bool

isSecondHalf() ¶ public

isSecondHalf(): bool

Determines if the instance is within the second half of year

Returns

bool

isSunday() ¶ public

isSunday(): bool

Checks if this day is a Sunday.

Returns

bool

isThursday() ¶ public

isThursday(): bool

Checks if this day is a Thursday.

Returns

bool

isToday() ¶ public

isToday(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is today

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isTomorrow() ¶ public

isTomorrow(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is tomorrow

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

isTuesday() ¶ public

isTuesday(): bool

Checks if this day is a Tuesday.

Returns

bool

isWednesday() ¶ public

isWednesday(): bool

Checks if this day is a Wednesday.

Returns

bool

isWeekday() ¶ public

isWeekday(): bool

Determines if the instance is a weekday

Returns

bool

isWeekend() ¶ public

isWeekend(): bool

Determines if the instance is a weekend day

Returns

bool

isWithinNext() ¶ public

isWithinNext(string|int $timeInterval): bool

Returns true this instance will happen within the specified interval

Parameters

string|int $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.

Returns

bool

isYesterday() ¶ public

isYesterday(DateTimeZone|string|null $timezone = null): bool

Determines if the instance is yesterday

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

bool

jsonSerialize() ¶ public

jsonSerialize(): string|int

Returns a string that should be serialized when converting this object to JSON

Returns

string|int

lastOfMonth() ¶ public

lastOfMonth(int|null $dayOfWeek = null): static

Modify to the last occurrence of a given day of the week in the current month. If no dayOfWeek is provided, modify to the last day of the current month. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

lastOfQuarter() ¶ public

lastOfQuarter(int|null $dayOfWeek = null): static

Modify to the last occurrence of a given day of the week in the current quarter. If no dayOfWeek is provided, modify to the last day of the current quarter. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

lastOfYear() ¶ public

lastOfYear(int|null $dayOfWeek = null): static

Modify to the last occurrence of a given day of the week in the current year. If no dayOfWeek is provided, modify to the last day of the current year. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

lessThan() ¶ public

lessThan(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is less (before) than another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

lessThanOrEquals() ¶ public

lessThanOrEquals(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is less (before) or equal to another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

modify() ¶ public

modify(string $modifier): static

Creates a new instance with date modified according to DateTimeImmutable::modifier().

Attempting to change a time component will raise an exception

Parameters

string $modifier: Date modifier

Returns

static

month() ¶ public

month(int $value): static

Set the instance's month

Parameters

int $value: The month value.

Returns

static

next() ¶ public

next(int|null $dayOfWeek = null): static

Modify to the next occurrence of a given day of the week. If no dayOfWeek is provided, modify to the next occurrence of the current day of the week. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

nice() ¶ public

nice(string|null $locale = null): string

Returns a nicely formatted date string for this object.

The format to be used is stored in the static property Date::$niceFormat.

Parameters

string|null $locale optional: The locale name in which the date should be displayed (e.g. pt-BR)

Returns

string

notEquals() ¶ public

notEquals(Cake\Chronos\ChronosDate $other): bool

Determines if the instance is not equal to another

Parameters

Cake\Chronos\ChronosDate $other: The instance to compare with.

Returns

bool

now() ¶ public static

now(DateTimeZone|string|null $timezone = null): static

Get today's date.

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for now.

Returns

static

nthOfMonth() ¶ public

nthOfMonth(int $nth, int $dayOfWeek): static|false

Modify to the given occurrence of a given day of the week in the current month. If the calculated occurrence is outside the scope of the current month, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int $nth: The offset to use.
int $dayOfWeek: The day of the week to move to.

Returns

static|false

nthOfQuarter() ¶ public

nthOfQuarter(int $nth, int $dayOfWeek): static|false

Modify to the given occurrence of a given day of the week in the current quarter. If the calculated occurrence is outside the scope of the current quarter, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int $nth: The offset to use.
int $dayOfWeek: The day of the week to move to.

Returns

static|false

nthOfYear() ¶ public

nthOfYear(int $nth, int $dayOfWeek): static|false

Modify to the given occurrence of a given day of the week in the current year. If the calculated occurrence is outside the scope of the current year, then return false and no modifications are made. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int $nth: The offset to use.
int $dayOfWeek: The day of the week to move to.

Returns

static|false

parse() ¶ public static

parse(Cake\Chronos\ChronosDateDateTimeInterface|string $time): static

Create an instance from a string. This is an alias for the constructor that allows better fluent syntax as it allows you to do Chronos::parse('Monday next week')->fn() rather than (new Chronos('Monday next week'))->fn()

Parameters

Cake\Chronos\ChronosDateDateTimeInterface|string $time: The strtotime compatible string to parse

Returns

static

parseDate() ¶ public static

parseDate(string $date, string|int|null $format = null): static|null

Returns a new Date object after parsing the provided $date string based on the passed or configured format. This method is locale dependent, Any string that is passed to this function will be interpreted as a locale dependent string.

When no $format is provided, the wordFormat format will be used.

If it was impossible to parse the provided time, null will be returned.

Example:

 $time = Date::parseDate('10/13/2013');
 $time = Date::parseDate('13 Oct, 2013', 'dd MMM, y');
 $time = Date::parseDate('13 Oct, 2013', IntlDateFormatter::SHORT);

Parameters

string $date: The date string to parse.
string|int|null $format optional: Any format accepted by IntlDateFormatter.

Returns

static|null

previous() ¶ public

previous(int|null $dayOfWeek = null): static

Modify to the previous occurrence of a given day of the week. If no dayOfWeek is provided, modify to the previous occurrence of the current day of the week. Use the supplied consts to indicate the desired dayOfWeek, ex. Chronos::MONDAY.

Parameters

int|null $dayOfWeek optional: The day of the week to move to.

Returns

static

resetToStringFormat() ¶ public static

resetToStringFormat(): void

Resets the __toString() format to DEFAULT_TO_STRING_FORMAT.

Returns

void

setDate() ¶ public

setDate(int $year, int $month, int $day): static

Sets the date.

Parameters

int $year: The year to set.
int $month: The month to set.
int $day: The day to set.

Returns

static

setISODate() ¶ public

setISODate(int $year, int $week, int $dayOfWeek = 1): static

Sets the date according to the ISO 8601 standard

Parameters

int $year: Year of the date.
int $week: Week of the date.
int $dayOfWeek optional: Offset from the first day of the week.

Returns

static

setJsonEncodeFormat() ¶ public static

setJsonEncodeFormat(Closure|string|int $format): void

Sets the default format used when converting this object to JSON

The format should be either the formatting constants from IntlDateFormatter as described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern as specified in (http://www.icu-project.org/apiref/icu4c/classSimpleDateFormat.html#details)

Alternatively, the format can provide a callback. In this case, the callback can receive this object and return a formatted string.

Parameters

Closure|string|int $format: Format.

Returns

void

setToStringFormat() ¶ public static

setToStringFormat(string|int $format): void

Sets the default format used when type converting instances of this type to string

The format should be either the formatting constants from IntlDateFormatter as described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern as specified in (https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html#details)

Parameters

string|int $format: Format.

Returns

void

startOfCentury() ¶ public

startOfCentury(): static

Resets the date to the first day of the century

Returns

static

startOfDecade() ¶ public

startOfDecade(): static

Resets the date to the first day of the decade

Returns

static

startOfMonth() ¶ public

startOfMonth(): static

Resets the date to the first day of the month

Returns

static

startOfWeek() ¶ public

startOfWeek(): static

Resets the date to the first day of week (defined in $weekStartsAt)

Returns

static

startOfYear() ¶ public

startOfYear(): static

Resets the date to the first day of the year

Returns

static

sub() ¶ public

sub(DateInterval $interval): static

Subtract an Interval from a Date.

Any changes to the time will be ignored and reset to 00:00:00

Parameters

DateInterval $interval: The interval to modify this date by.

Returns

static

subDays() ¶ public

subDays(int $value): static

Remove days from the instance

Parameters

int $value: The number of days to remove.

Returns

static

subMonths() ¶ public

subMonths(int $value): static

Remove months from the instance

Has the same behavior as addMonths().

Parameters

int $value: The number of months to remove.

Returns

static

subMonthsWithOverflow() ¶ public

subMonthsWithOverflow(int $value): static

Add months with overflowing to the instance. Positive $value travels forward while negative $value travels into the past.

If the new ChronosDate does not exist, the days overflow into the next month.

Example:

 (new Chronos('2012-01-30'))->addMonthsWithOverflow(1); // Results in 2013-03-01

Parameters

int $value: The number of months to remove.

Returns

static

subWeekdays() ¶ public

subWeekdays(int $value): static

Remove weekdays from the instance

Parameters

int $value: The number of weekdays to remove.

Returns

static

subWeeks() ¶ public

subWeeks(int $value): static

Remove weeks to the instance

Parameters

int $value: The number of weeks to remove.

Returns

static

subYears() ¶ public

subYears(int $value): static

Remove years from the instance.

Has the same behavior as addYears().

Parameters

int $value: The number of years to remove.

Returns

static

subYearsWithOverflow() ¶ public

subYearsWithOverflow(int $value): static

Remove years with overflow from the instance

Has the same behavior as addYeasrWithOverflow().

Parameters

int $value: The number of years to remove.

Returns

static

timeAgoInWords() ¶ public

timeAgoInWords(array<string, mixed> $options = []): string

Returns either a relative or a formatted absolute date depending on the difference between the current date and this object.

Options:

from => another Date object representing the "now" date
format => a fall back format if the relative time is longer than the duration specified by end
accuracy => Specifies how accurate the date should be described (array)
- year => The format if years > 0 (default "day")
- month => The format if months > 0 (default "day")
- week => The format if weeks > 0 (default "day")
- day => The format if weeks > 0 (default "day")
end => The end of relative date telling
relativeString => The printf compatible string when outputting relative date
absoluteString => The printf compatible string when outputting absolute date
timezone => The user timezone the timestamp should be formatted in.

Relative dates look something like this:

3 weeks, 4 days ago
1 day ago

Default date formatting is d/M/YY e.g: on 18/2/09. Formatting is done internally using i18nFormat, see the method for the valid formatting strings.

The returned string includes 'ago' or 'on' and assumes you'll properly add a word like 'Posted ' before the function output.

NOTE: If the difference is one week or more, the lowest level of accuracy is day.

Parameters

array<string, mixed> $options optional: Array of options.

Returns

string

toAtomString() ¶ public

toAtomString(): string

Format the instance as ATOM

Returns

string

toCookieString() ¶ public

toCookieString(): string

Format the instance as COOKIE

Returns

string

toDateString() ¶ public

toDateString(): string

Format the instance as date

Returns

string

toDateTimeImmutable() ¶ public

toDateTimeImmutable(DateTimeZone|string|null $timezone = null): DateTimeImmutable

Returns the date as a DateTimeImmutable instance at midnight.

Parameters

DateTimeZone|string|null $timezone optional: Time zone the DateTimeImmutable instance will be in

Returns

DateTimeImmutable

toDateTimeString() ¶ public

toDateTimeString(): string

Format the instance as date and time

Returns

string

toDayDateTimeString() ¶ public

toDayDateTimeString(): string

Format the instance with day, date and time

Returns

string

toFormattedDateString() ¶ public

toFormattedDateString(): string

Format the instance as a readable date

Returns

string

toIso8601String() ¶ public

toIso8601String(): string

Format the instance as ISO8601

Returns

string

toNative() ¶ public

toNative(DateTimeZone|string|null $timezone = null): DateTimeImmutable

Returns the date as a DateTimeImmutable instance at midnight.

Alias of toDateTimeImmutable().

Parameters

DateTimeZone|string|null $timezone optional: Time zone the DateTimeImmutable instance will be in

Returns

DateTimeImmutable

toQuarter() ¶ public

toQuarter(bool $range = false): array|int

Returns the quarter

Parameters

bool $range optional: Range.

Returns

array|int

toRfc1036String() ¶ public

toRfc1036String(): string

Format the instance as RFC1036

Returns

string

Links

https://tools.ietf.org/html/rfc1036

toRfc1123String() ¶ public

toRfc1123String(): string

Format the instance as RFC1123

Returns

string

Links

https://tools.ietf.org/html/rfc1123

toRfc2822String() ¶ public

toRfc2822String(): string

Format the instance as RFC2822

Returns

string

Links

https://tools.ietf.org/html/rfc2822

toRfc3339String() ¶ public

toRfc3339String(): string

Format the instance as RFC3339

Returns

string

Links

https://tools.ietf.org/html/rfc3339

toRfc822String() ¶ public

toRfc822String(): string

Format the instance as RFC822

Returns

string

Links

https://tools.ietf.org/html/rfc822

toRfc850String() ¶ public

toRfc850String(): string

Format the instance as RFC850

today(DateTimeZone|string|null $timezone = null): static

Get today's date.

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for today.

Returns

static

tomorrow() ¶ public static

tomorrow(DateTimeZone|string|null $timezone = null): static

Get tomorrow's date.

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for tomorrow.

Returns

static

wasWithinLast() ¶ public

wasWithinLast(string|int $timeInterval): bool

Returns true this instance happened within the specified interval

Parameters

string|int $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute.

Returns

bool

year() ¶ public

year(int $value): static

Set the instance's year

Parameters

int $value: The year value.

Returns

static

yesterday() ¶ public static

yesterday(DateTimeZone|string|null $timezone = null): static

Get yesterday's date.

Parameters

DateTimeZone|string|null $timezone optional: Time zone to use for yesterday.

Returns

static

Property Detail

`$_jsonEncodeFormat` ¶ protected static

The format to use when converting this object to JSON.

The format should be either the formatting constants from IntlDateFormatter as described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern as specified in (https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html#details)

Type

Closure|string|int

`$_toStringFormat` ¶ protected static

The format to use when formatting a time using Cake\I18n\Date::i18nFormat() and __toString.

The format should be either the formatting constants from IntlDateFormatter as described in (https://secure.php.net/manual/en/class.intldateformatter.php) or a pattern as specified in (https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html#details)

Type

string|int

`$age` ¶ public @property-read

does a diffInYears() with default parameters

Type

int

`$day` ¶ public @property-read

int<1, 12>

`$native` ¶ protected

Type

DateTimeImmutable

`$niceFormat` ¶ public static

The format to use when formatting a time using Cake\I18n\Date::nice()

Type

int

`$yearIso` ¶ public @property-read

Type

int

Namespaces

Class Date

Constants

Property Summary

Method Summary

__construct() public

__debugInfo() public

__get() public

__isset() public

__toString() public

_formatObject() protected

_parseDateTime() protected static

add() public

addDays() public

addMonths() public

addMonthsWithOverflow() public

addWeekdays() public

addWeeks() public

addYears() public

addYearsWithOverflow() public

between() public

closest() public

create() public static

createFromArray() public static

createFromFormat() public static

createNative() protected

day() public

diff() public

diffFiltered() public

diffForHumans() public

diffFormatter() public static

diffInDays() public

diffInDaysFiltered() public

diffInMonths() public

diffInWeekdays() public

diffInWeekendDays() public

diffInWeeks() public

diffInYears() public

endOfCentury() public

endOfDecade() public

endOfMonth() public

endOfWeek() public

endOfYear() public

equals() public

farthest() public

firstOfMonth() public

firstOfQuarter() public

firstOfYear() public

format() public

getLastErrors() public static

greaterThan() public

greaterThanOrEquals() public

i18nFormat() public

isFirstHalf() public

isFriday() public

isFuture() public

isLastMonth() public

isLastWeek() public

isLastYear() public

isLeapYear() public

isMonday() public

isNextMonth() public

isNextWeek() public

isNextYear() public

isPast() public

isSaturday() public

isSecondHalf() public

isSunday() public

isThursday() public

isToday() public

isTomorrow() public

isTuesday() public

isWednesday() public

isWeekday() public

isWeekend() public

isWithinNext() public

isYesterday() public

jsonSerialize() public

lastOfMonth() public

lastOfQuarter() public