W3cubDocs

/CakePHP 4.4

Class FrozenTime

Extends the built-in DateTime class to provide handy methods and locale-aware formatting helpers

This object provides an immutable variant of {@link \Cake\I18n\Time}

Namespace: Cake\I18n

Constants

int

DAYS_PER_WEEK
```
7
```
string

DEFAULT_TO_STRING_FORMAT
```
'Y-m-d H:i:s'
```
Default format to use for __toString method when type juggling occurs.
int

FRIDAY
```
5
```
int

HOURS_PER_DAY
```
24
```
int

MINUTES_PER_HOUR
```
60
```
int

MONDAY
```
1
```
int

MONTHS_PER_QUARTER
```
3
```
int

MONTHS_PER_YEAR
```
12
```
int

SATURDAY
```
6
```
int

SECONDS_PER_MINUTE
```
60
```
int

SUNDAY
```
7
```
int

THURSDAY
```
4
```
int

TUESDAY
```
2
```
string

UNIX_TIMESTAMP_FORMAT
```
'unixTimestampFormat'
```
serialise the value as a Unix Timestamp
int

WEDNESDAY
```
3
```
int

WEEKS_PER_YEAR
```
52
```
int

YEARS_PER_CENTURY
```
100
```
int

YEARS_PER_DECADE
```
10
```

Property Summary

$_formatters protected static

arrayIntlDateFormatter>

In-memory cache of date formatters
$_jsonEncodeFormat protected static

Closure|array<int>|string|int

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

array

Holds the last error generated by createFromFormat
$_toStringFormat protected static

array<int>|string|int

The format to use when formatting a time using Cake\I18n\FrozenTime::i18nFormat() and __toString. This format is also used by parseDateTime().
$age public @property-read

int

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

int
$dayOfWeek public @property-read

int

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

string
$dayOfYear public @property-read

int

0 through 365
$days protected static

array

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

int

number of days in the given month
$defaultLocale protected static

string|null

The default locale to be used for displaying formatted date strings.
$diffFormatter protected static

Cake\Chronos\DifferenceFormatterInterface

Instance of the diff formatting object.
$dst public @property-read

bool

daylight savings time indicator, true if DST, false otherwise
$hour public @property-read

int
$lenientParsing protected static

bool

Whether lenient parsing is enabled for IntlDateFormatter.
$local public @property-read

bool

checks if the timezone is local, true if local, false otherwise
$micro public @property-read

int
$microsecond public @property-read

int
$minute public @property-read

int
$month public @property-read

int
$niceFormat public static

array<int>|string|int

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

int

the timezone offset in seconds from UTC
$offsetHours public @property-read

int

the timezone offset in hours from UTC
$quarter public @property-read

int

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

string

Regex for relative period.
$second public @property-read

int
$testNow protected static

Cake\Chronos\ChronosInterface|null

A test ChronosInterface instance to be returned when now instances are created
$timestamp public @property-read

int

seconds since the Unix Epoch
$timezone public @property-read

DateTimeZone

the current timezone
$timezoneName public @property-read

string
$toStringFormat protected static

string

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

DateTimeZone

alias of timezone
$tzName public @property-read

string
$utc public @property-read

bool

checks if the timezone is UTC, true if UTC, false otherwise
$weekEndsAt protected static

int

Last day of week
$weekOfMonth public @property-read

int

1 through 5
$weekOfYear public @property-read

int

ISO-8601 week number of year, weeks starting on Monday
$weekStartsAt protected static

int

First day of week
$weekendDays protected static

array

Days of weekend
$wordAccuracy public static

array<string>

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

string

The end of relative time telling
$wordFormat public static

array<int>|string|int

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

int
$yearIso public @property-read

int

Method Summary

__construct() public

Create a new immutable time instance.
__debugInfo() public

Returns the data that should be displayed when debugging this object
__get() public

Get a part of the ChronosInterface object
__isset() public

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

Format the instance as a string using the set format
_formatObject() protected

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

Add a day to the instance
addDays() public

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

Add an hour to the instance
addHours() public

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

Add a minute to the instance
addMinutes() public

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

Add a month to the instance.
addMonthWithOverflow() public

Add a month with overflow to the instance.
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.
addSecond() public

Add a second to the instance
addSeconds() public

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

Add a week to the instance
addWeekday() public

Add a weekday to the instance
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.
addYear() public

Add a year to the instance
addYearWithOverflow() public

Add a year with overflow to the instance
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.
average() public

Modify the current instance to the average of a given instance (default now) and the current instance.
between() public

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

Get the closest date from the instance.
copy() public

Get a copy of the instance
create() public static

Create a new ChronosInterface instance from a specific date and time.
createFromArray() public static

Creates a ChronosInterface instance from an array of date and time values.
createFromDate() public static

Create a ChronosInterface instance from just a date. The time portion is set to now.
createFromFormat() public static

Create a ChronosInterface instance from a specific format
createFromTime() public static

Create a ChronosInterface instance from just a time. The date portion is set to today.
createFromTimestamp() public static

Create a ChronosInterface instance from a timestamp
createFromTimestampUTC() public static

Create a ChronosInterface instance from an UTC timestamp
day() public

Set the instance's day
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 or overwrite the current one.
diffInDays() public

Get the difference in days
diffInDaysFiltered() public

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

Get the difference in hours
diffInHoursFiltered() public

Get the difference in hours using a filter callable
diffInMinutes() public

Get the difference in minutes
diffInMonths() public

Get the difference in months
diffInMonthsIgnoreTimezone() public

Get the difference in months ignoring the timezone. This means the months are calculated in the specified timezone without converting to UTC first. This prevents the day from changing which can change the month.
diffInSeconds() public

Get the difference in seconds
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
disableLenientParsing() public static

Enables lenient parsing for locale formats.
enableLenientParsing() public static

Enables lenient parsing for locale formats.
endOfCentury() public

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

Resets the time to 23:59:59
endOfDecade() public

Resets the date to end of the decade and time to 23:59:59
endOfMonth() public

Resets the date to end of the month and time to 23:59:59
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 and time to 23:59:59
eq() public

Determines if the instance is equal to another
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. static::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. static::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. static::MONDAY.
fromNow() public static

Convenience method for getting the remaining time from a given time.
getDefaultLocale() public static

Gets the default locale.
getDiffFormatter() public static

Get the difference formatter instance.
getLastErrors() public static

Returns any errors or warnings that were found during the parsing of the last object created by this class.
getTestNow() public static

Get the ChronosInterface instance (real or mock) to be returned when a "now" instance is created.
getWeekEndsAt() public static

Get the last day of week
getWeekStartsAt() public static

Get the first day of week
getWeekendDays() public static

Get weekend days
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
gt() public

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

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

Determine if there is a relative keyword in the time string, this is to create dates relative to now for test instances. e.g.: next tuesday
hasTestNow() public static

Determine if there is a valid test instance set. A valid test instance is anything that is not null.
hour() public

Set the instance's hour
i18nFormat() public

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

Create a ChronosInterface instance from a DateTimeInterface one
isBirthday() public

Check if its the birthday. Compares the date/month values of the two dates.
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.
isMutable() public

Check if instance of ChronosInterface is mutable.
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
isSameDay() public

Checks if the passed in date is the same day as the instance current day.
isSaturday() public

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

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

Returns true if this object represents a date within the current month
isThisWeek() public

Returns true if this object represents a date within the current week
isThisYear() public

Returns true if this object represents a date within the current year
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. static::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. static::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. static::MONDAY.
lenientParsingEnabled() public static

Gets whether locale format parsing is set to lenient.
lessThan() public

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

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

Get list of timezone identifiers
lt() public

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

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

Get the maximum instance between a given instance (default now) and the current instance.
maxValue() public static

Create a ChronosInterface instance for the greatest supported date.
microsecond() public

Set the instance's microsecond
min() public

Get the minimum instance between a given instance (default now) and the current instance.
minValue() public static

Create a ChronosInterface instance for the lowest supported date.
minute() public

Set the instance's minute
modify() public @method
month() public

Set the instance's month
ne() public

Determines if the instance is not equal to another
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. static::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 a ChronosInterface instance for the current date and time
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. static::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. static::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. static::MONDAY.
parse() public static

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

Returns a new Time object after parsing the provided $date 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.
parseDateTime() public 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.
parseTime() public 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.
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. static::MONDAY.
resetToStringFormat() public static

Resets the format used to the default when converting an instance of this type to a string
safeCreateDateTimeZone() protected static

Creates a DateTimeZone from a string or a DateTimeZone
second() public

Set the instance's second
secondsSinceMidnight() public

The number of seconds since midnight.
secondsUntilEndOfDay() public

The number of seconds until 23:59:59.
setDate() public

Set the date to a different date.
setDateTime() public

Set the date and time all together
setDefaultLocale() public static

Sets the default locale.
setDiffFormatter() public static

Set the difference formatter instance.
setJsonEncodeFormat() public static

Sets the default format used when converting this object to JSON
setTestNow() public static
Set a ChronosInterface instance (real or mock) to be returned when a "now" instance is created. The provided instance will be returned specifically under the following conditions:
- A call to the static now() method, ex. ChronosInterface::now()
- When a null (or blank string) is passed to the constructor or parse(), ex. new Chronos(null)
- When the string "now" is passed to the constructor or parse(), ex. new Chronos('now')
- When a string containing the desired time is passed to ChronosInterface::parse()
setTimeFromTimeString() public

Set the time by time string
setTimezone() public

Set the instance's timezone from a string or object
setToStringFormat() public static

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

Set the last day of week
setWeekStartsAt() public static

Set the first day of week
setWeekendDays() public static

Set weekend days
startOfCentury() public

Resets the date to the first day of the century and the time to 00:00:00
startOfDay() public

Resets the time to 00:00:00
startOfDecade() public

Resets the date to the first day of the decade and the time to 00:00:00
startOfMonth() public

Resets the date to the first day of the month and the time to 00:00:00
startOfWeek() public

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

Resets the date to the first day of the year and the time to 00:00:00
subDay() public

Remove a day from the instance
subDays() public

Remove days from the instance
subHour() public

Remove an hour from the instance
subHours() public

Remove hours from the instance
subMinute() public

Remove a minute from the instance
subMinutes() public

Remove minutes from the instance
subMonth() public

Remove a month from the instance
subMonthWithOverflow() public

Remove a month with overflow from the instance.
subMonths() public

Remove months from the instance.
subMonthsWithOverflow() public

Remove months with overflow from the instance.
subSecond() public

Remove a second from the instance
subSeconds() public

Remove seconds from the instance
subWeek() public

Remove a week from the instance
subWeekday() public

Remove a weekday from the instance
subWeekdays() public

Remove weekdays from the instance
subWeeks() public

Remove weeks to the instance
subYear() public

Remove a year from the instance.
subYearWithOverflow() public

Remove a year with overflow from 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 time and this object.
timestamp() public

Set the instance's timestamp
timezone() public

Alias for setTimezone()
toAtomString() public

Format the instance as ATOM
toCookieString() public

Format the instance as COOKIE
toDateString() public

Format the instance as date
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
toMutable() public

Create a new mutable instance from current immutable instance.
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
today() public static

Create a ChronosInterface instance for today
tomorrow() public static

Create a ChronosInterface instance for tomorrow
tz() public

Alias for setTimezone()
wasWithinLast() public

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

Set the instance's year
yesterday() public static

Create a ChronosInterface instance for yesterday

Method Detail

__construct() public

__construct(DateTimeInterface|string|int|null $time = null, DateTimeZone|string|null $tz = null)

Create a new immutable time instance.

Please see the testing aids section (specifically static::setTestNow()) for more on the possibility of this constructor returning a test instance.

Parameters

DateTimeInterface|string|int|null $time optional: Fixed or relative time
DateTimeZone|string|null $tz optional: The timezone for the instance

__debugInfo() public

__debugInfo(): array<string, mixed>

Returns the data that should be displayed when debugging this object

Returns

array<string, mixed>

__get() public

__get(string $name): string|int|boolDateTimeZone

Get a part of the ChronosInterface object

Parameters

string $name: The property name to read.

Returns

string|int|boolDateTimeZone

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

Format the instance as a string using the set format

Returns

string

_formatObject() protected

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

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

Parameters

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

Returns

string

addDay() public

addDay(int $value = 1): static

Add a day to the instance

Parameters

int $value optional: The number of days to add.

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

addHour() public

addHour(int $value = 1): static

Add an hour to the instance

Parameters

int $value optional: The number of hours to add.

Returns

static

addHours() public

addHours(int $value): static

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

Parameters

int $value: The number of hours to add.

Returns

static

addMinute() public

addMinute(int $value = 1): static

Add a minute to the instance

Parameters

int $value optional: The number of minutes to add.

Returns

static

addMinutes() public

addMinutes(int $value): static

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

Parameters

int $value: The number of minutes to add.

Returns

static

addMonth() public

addMonth(int $value = 1): static

Add a month to the instance.

Has the same behavior as addMonths().

Parameters

int $value optional: The number of months to add.

Returns

static

addMonthWithOverflow() public

addMonthWithOverflow(int $value = 1): static

Add a month with overflow to the instance.

Has the same behavior as addMonthsWithOverflow().

Parameters

int $value optional: The number of months 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.

If the new date 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'))->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 date 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

addSecond() public

addSecond(int $value = 1): static

Add a second to the instance

Parameters

int $value optional: The number of seconds to add.

Returns

static

addSeconds() public

addSeconds(int $value): static

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

Parameters

int $value: The number of seconds to add.

Returns

static

addWeek() public

addWeek(int $value = 1): static

Add a week to the instance

Parameters

int $value optional: The number of weeks to add.

Returns

static

addWeekday() public

addWeekday(int $value = 1): static

Add a weekday to the instance

Parameters

int $value optional: The number of weekdays 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

addYear() public

addYear(int $value = 1): static

Add a year to the instance

Has the same behavior as addYears().

Parameters

int $value optional: The number of years to add.

Returns

static

addYearWithOverflow() public

addYearWithOverflow(int $value = 1): static

Add a year with overflow to the instance

Has the same behavior as addYearsWithOverflow().

Parameters

int $value optional: The number of years 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 date 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 date 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

average() public

average(Cake\Chronos\ChronosInterface $dt = null): static

Modify the current instance to the average of a given instance (default now) and the current instance.

Parameters

Cake\Chronos\ChronosInterface $dt optional: The instance to compare with.

Returns

static

between() public

between(Cake\Chronos\ChronosInterface $dt1, Cake\Chronos\ChronosInterface $dt2, bool $equal = true): bool

Determines if the instance is between two others

Parameters

Cake\Chronos\ChronosInterface $dt1: The instance to compare with.
Cake\Chronos\ChronosInterface $dt2: The instance to compare with.
bool $equal optional: Indicates if a > and < comparison should be used or <= or >=

Returns

bool

closest() public

closest(Cake\Chronos\ChronosInterface $dt1, Cake\Chronos\ChronosInterface $dt2): static

Get the closest date from the instance.

Parameters

Cake\Chronos\ChronosInterface $dt1: The instance to compare with.
Cake\Chronos\ChronosInterface $dt2: The instance to compare with.

Returns

static

copy() public

copy(): static

Get a copy of the instance

Returns

static

create() public static

create(int|null $year = null, int|null $month = null, int|null $day = null, int|null $hour = null, int|null $minute = null, int|null $second = null, int|null $microsecond = null, DateTimeZone|string|null $tz = null): static

Create a new ChronosInterface instance from a specific date and time.

If any of $year, $month or $day are set to null their now() values will be used.

If $hour is null it will be set to its now() value and the default values for $minute, $second and $microsecond will be their now() values. If $hour is not null then the default values for $minute, $second and $microsecond will be 0.

Parameters

int|null $year optional: The year to create an instance with.
int|null $month optional: The month to create an instance with.
int|null $day optional: The day to create an instance with.
int|null $hour optional: The hour to create an instance with.
int|null $minute optional: The minute to create an instance with.
int|null $second optional: The second to create an instance with.
int|null $microsecond optional: The microsecond to create an instance with.
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

createFromArray() public static

createFromArray((int|string)[] $values): static

Creates a ChronosInterface instance from an array of date and time values.

The 'year', 'month' and 'day' values must all be set for a date. The time values all default to 0.

The 'timezone' value can be any format supported by \DateTimeZone.

Allowed values:

year
month
day
hour
minute
second
microsecond
meridian ('am' or 'pm')
timezone

Parameters

(int|string)[] $values: Array of date and time values.

Returns

static

createFromDate() public static

createFromDate(int|null $year = null, int|null $month = null, int|null $day = null, DateTimeZone|string|null $tz = null): static

Create a ChronosInterface instance from just a date. The time portion is set to now.

Parameters

int|null $year optional: The year to create an instance with.
int|null $month optional: The month to create an instance with.
int|null $day optional: The day to create an instance with.
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

createFromFormat() public static

createFromFormat(string $format, string $time, DateTimeZone|string|null $tz = null): static

Create a ChronosInterface instance from a specific format

Parameters

string $format: The date() compatible format string.
string $time: The formatted date string to interpret.
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

Throws

InvalidArgumentException

createFromTime() public static

createFromTime(int|null $hour = null, int|null $minute = null, int|null $second = null, int|null $microsecond = null, DateTimeZone|string|null $tz = null): static

Create a ChronosInterface instance from just a time. The date portion is set to today.

Parameters

int|null $hour optional: The hour to create an instance with.
int|null $minute optional: The minute to create an instance with.
int|null $second optional: The second to create an instance with.
int|null $microsecond optional: The microsecond to create an instance with.
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

createFromTimestamp() public static

createFromTimestamp(int $timestamp, DateTimeZone|string|null $tz = null): static

Create a ChronosInterface instance from a timestamp

Parameters

int $timestamp: The timestamp to create an instance from.
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

createFromTimestampUTC() public static

createFromTimestampUTC(int $timestamp): static

Create a ChronosInterface instance from an UTC timestamp

Parameters

int $timestamp: The UTC timestamp to create an instance from.

Returns

static

day() public

day(int $value): static

Set the instance's day

Parameters

int $value: The day value.

Returns

static

diffFiltered() public

diffFiltered(Cake\Chronos\ChronosInterval $ci, callable $callback, Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference by the given interval using a filter callable

Parameters

Cake\Chronos\ChronosInterval $ci: An interval to traverse by
callable $callback: The callback to use for filtering.
Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffForHumans() public

diffForHumans(Cake\Chronos\ChronosInterface|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: 1 hour ago 5 months ago

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

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

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

Parameters

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

Returns

string

diffFormatter() public static

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

Get the difference formatter instance or overwrite the current one.

Parameters

Cake\Chronos\DifferenceFormatterInterface|null $formatter optional: The formatter instance when setting.

Returns

Cake\Chronos\DifferenceFormatterInterface

diffInDays() public

diffInDays(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in days

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInDaysFiltered() public

diffInDaysFiltered(callable $callback, Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in days using a filter callable

Parameters

callable $callback: The callback to use for filtering.
Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInHours() public

diffInHours(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in hours

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInHoursFiltered() public

diffInHoursFiltered(callable $callback, Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in hours using a filter callable

Parameters

callable $callback: The callback to use for filtering.
Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInMinutes() public

diffInMinutes(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in minutes

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInMonths() public

diffInMonths(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in months

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInMonthsIgnoreTimezone() public

diffInMonthsIgnoreTimezone(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in months ignoring the timezone. This means the months are calculated in the specified timezone without converting to UTC first. This prevents the day from changing which can change the month.

For example, if comparing 2019-06-01 Asia/Tokyo and 2019-10-01 Asia/Tokyo, the result would be 4 months instead of 3 when using normal DateTime::diff().

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInSeconds() public

diffInSeconds(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in seconds

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInWeekdays() public

diffInWeekdays(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in weekdays

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInWeekendDays() public

diffInWeekendDays(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in weekend days using a filter

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInWeeks() public

diffInWeeks(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in weeks

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

diffInYears() public

diffInYears(Cake\Chronos\ChronosInterface|null $dt = null, bool $abs = true): int

Get the difference in years

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to difference from.
bool $abs optional: Get the absolute of the difference

Returns

int

disableLenientParsing() public static

disableLenientParsing(): void

Enables lenient parsing for locale formats.

Returns

void

enableLenientParsing() public static

enableLenientParsing(): void

Enables lenient parsing for locale formats.

Returns

void

endOfCentury() public

endOfCentury(): static

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

Returns

static

endOfDay() public

endOfDay(): static

Resets the time to 23:59:59

Returns

static

endOfDecade() public

endOfDecade(): static

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

Returns

static

endOfMonth() public

endOfMonth(): static

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

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 and time to 23:59:59

Returns

static

eq() public

eq(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is equal to another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

equals() public

equals(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is equal to another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

farthest() public

farthest(Cake\Chronos\ChronosInterface $dt1, Cake\Chronos\ChronosInterface $dt2): static

Get the farthest date from the instance.

Parameters

Cake\Chronos\ChronosInterface $dt1: The instance to compare with.
Cake\Chronos\ChronosInterface $dt2: The instance to compare with.

Returns

static

firstOfMonth() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

firstOfQuarter() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

firstOfYear() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

fromNow() public static

fromNow(DateTimeDateTimeImmutable $datetime): DateInterval|bool

Convenience method for getting the remaining time from a given time.

Parameters

DateTimeDateTimeImmutable $datetime: The date to get the remaining time from.

Returns

DateInterval|bool

getDefaultLocale() public static

getDefaultLocale(): string|null

Gets the default locale.

Returns

string|null

getDiffFormatter() public static

getDiffFormatter(): Cake\Chronos\DifferenceFormatterInterface

Get the difference formatter instance.

Returns

Cake\Chronos\DifferenceFormatterInterface

getLastErrors() public static

getLastErrors(): array

Returns any errors or warnings that were found during the parsing of the last object created by this class.

Returns

array

getTestNow() public static

getTestNow(): Cake\Chronos\ChronosInterface|null

Get the ChronosInterface instance (real or mock) to be returned when a "now" instance is created.

Returns

Cake\Chronos\ChronosInterface|null

getWeekEndsAt() public static

getWeekEndsAt(): int

Get the last day of week

Returns

int

getWeekStartsAt() public static

getWeekStartsAt(): int

Get the first day of week

Returns

int

getWeekendDays() public static

getWeekendDays(): array

Get weekend days

Returns

array

greaterThan() public

greaterThan(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is greater (after) than another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

greaterThanOrEquals() public

greaterThanOrEquals(Cake\Chronos\ChronosInterface $dt): bool

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

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

gt() public

gt(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is greater (after) than another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

gte() public

gte(Cake\Chronos\ChronosInterface $dt): bool

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

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

hasRelativeKeywords() public static

hasRelativeKeywords(string|null $time): bool

Determine if there is a relative keyword in the time string, this is to create dates relative to now for test instances. e.g.: next tuesday

Parameters

string|null $time: The time string to check.

Returns

bool

hasTestNow() public static

hasTestNow(): bool

Determine if there is a valid test instance set. A valid test instance is anything that is not null.

Returns

bool

hour() public

hour(int $value): static

Set the instance's hour

Parameters

int $value: The hour value.

Returns

static

i18nFormat() public

i18nFormat(string|int|null $format = null, DateTimeZone|string|null $timezone = 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.

Additional to IntlDateFormatter constants and date formatting string you can use Time::UNIX_TIMESTAMP_FORMAT to get a unix timestamp

Examples

$time = new Time('2014-04-20 22:10');
$time->i18nFormat(); // outputs '4/20/14, 10:10 PM' for the en-US locale
$time->i18nFormat(\IntlDateFormatter::FULL); // Use the full date and time format
$time->i18nFormat([\IntlDateFormatter::FULL, \IntlDateFormatter::SHORT]); // Use full date but short time format
$time->i18nFormat('yyyy-MM-dd HH:mm:ss'); // outputs '2014-04-20 22:10'
$time->i18nFormat(Time::UNIX_TIMESTAMP_FORMAT); // outputs '1398031800'

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

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

If you need to display the date in a different timezone than the one being used for this Time object without altering its internal state, you can pass a timezone string or object as the second parameter.

Finally, 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

$time = new Time('2014-04-20 22:10');
$time->i18nFormat(null, null, 'de-DE');
$time->i18nFormat(\IntlDateFormatter::FULL, 'Europe/Berlin', 'de-DE');

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

Parameters

string|int|null $format optional: Format string.
DateTimeZone|string|null $timezone optional: Timezone string or DateTimeZone object in which the date will be displayed. The timezone stored for this object will not be changed.
string|null $locale optional: The locale name in which the date should be displayed (e.g. pt-BR)

Returns

string|int

instance() public static

instance(DateTimeInterface $dt): static

Create a ChronosInterface instance from a DateTimeInterface one

Parameters

DateTimeInterface $dt: The datetime instance to convert.

Returns

static

isBirthday() public

isBirthday(Cake\Chronos\ChronosInterface $dt): bool

Check if its the birthday. Compares the date/month values of the two dates.

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

isFriday() public

isFriday(): bool

Checks if this day is a Friday.

Returns

bool

isFuture() public

isFuture(): bool

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

Returns

bool

isLastMonth() public

isLastMonth(): bool

Determines if the instance is within the last month

Returns

bool

isLastWeek() public

isLastWeek(): bool

Determines if the instance is within the last week

Returns

bool

isLastYear() public

isLastYear(): bool

Determines if the instance is within the last year

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

isMutable() public

isMutable(): bool

Check if instance of ChronosInterface is mutable.

Returns

bool

isNextMonth() public

isNextMonth(): bool

Determines if the instance is within the next month

Returns

bool

isNextWeek() public

isNextWeek(): bool

Determines if the instance is within the next week

Returns

bool

isNextYear() public

isNextYear(): bool

Determines if the instance is within the next year

Returns

bool

isPast() public

isPast(): bool

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

Returns

bool

isSameDay() public

isSameDay(Cake\Chronos\ChronosInterface $dt): bool

Checks if the passed in date is the same day as the instance current day.

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to check against.

Returns

bool

isSaturday() public

isSaturday(): bool

Checks if this day is a Saturday.

Returns

bool

isSunday() public

isSunday(): bool

Checks if this day is a Sunday.

Returns

bool

isThisMonth() public

isThisMonth(): bool

Returns true if this object represents a date within the current month

Returns

bool

isThisWeek() public

isThisWeek(): bool

Returns true if this object represents a date within the current week

Returns

bool

isThisYear() public

isThisYear(): bool

Returns true if this object represents a date within the current year

Returns

bool

isThursday() public

isThursday(): bool

Checks if this day is a Thursday.

Returns

bool

isToday() public

isToday(): bool

Determines if the instance is today

Returns

bool

isTomorrow() public

isTomorrow(): bool

Determines if the instance is tomorrow

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(): bool

Determines if the instance is yesterday

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): mixed

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. static::MONDAY.

Parameters

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

Returns

mixed

lastOfQuarter() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

lastOfYear() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

lenientParsingEnabled() public static

lenientParsingEnabled(): bool

Gets whether locale format parsing is set to lenient.

Returns

bool

lessThan() public

lessThan(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is less (before) than another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

lessThanOrEquals() public

lessThanOrEquals(Cake\Chronos\ChronosInterface $dt): bool

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

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

listTimezones() public static

listTimezones(string|int|null $filter = null, string|null $country = null, array<string, mixed>|bool $options = []): array

Get list of timezone identifiers

Parameters

string|int|null $filter optional: A regex to filter identifier Or one of DateTimeZone class constants
string|null $country optional: A two-letter ISO 3166-1 compatible country code. This option is only used when $filter is set to DateTimeZone::PER_COUNTRY
array<string, mixed>|bool $options optional: If true (default value) groups the identifiers list by primary region. Otherwise, an array containing group, abbr, before, and after keys. Setting group and abbr to true will group results and append timezone abbreviation in the display value. Set before and after to customize the abbreviation wrapper.

Returns

array

lt() public

lt(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is less (before) than another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

lte() public

lte(Cake\Chronos\ChronosInterface $dt): bool

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

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

max() public

max(Cake\Chronos\ChronosInterface|null $dt = null): static

Get the maximum instance between a given instance (default now) and the current instance.

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to compare with.

Returns

static

maxValue() public static

maxValue(): Cake\Chronos\ChronosInterface

Create a ChronosInterface instance for the greatest supported date.

Returns

Cake\Chronos\ChronosInterface

microsecond() public

microsecond(int $value): static

Set the instance's microsecond

Parameters

int $value: The microsecond value.

Returns

static

min() public

min(Cake\Chronos\ChronosInterface|null $dt = null): static

Get the minimum instance between a given instance (default now) and the current instance.

Parameters

Cake\Chronos\ChronosInterface|null $dt optional: The instance to compare with.

Returns

static

minValue() public static

minValue(): Cake\Chronos\ChronosInterface

Create a ChronosInterface instance for the lowest supported date.

Returns

Cake\Chronos\ChronosInterface

minute() public

minute(int $value): static

Set the instance's minute

Parameters

int $value: The minute value.

Returns

static

modify() public @method

modify(string $relative): Cake\Chronos\ChronosInterface

Parameters

string $relative

Returns

Cake\Chronos\ChronosInterface

month() public

month(int $value): static

Set the instance's month

Parameters

int $value: The month value.

Returns

static

ne() public

ne(Cake\Chronos\ChronosInterface $dt): bool

Determines if the instance is not equal to another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

next() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

nice() public

nice(DateTimeZone|string|null $timezone = null, 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 Time::niceFormat.

Parameters

DateTimeZone|string|null $timezone optional: Timezone string or DateTimeZone object in which the date will be displayed. The timezone stored for this object will not be changed.
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\ChronosInterface $dt): bool

Determines if the instance is not equal to another

Parameters

Cake\Chronos\ChronosInterface $dt: The instance to compare with.

Returns

bool

now() public static

now(DateTimeZone|string|null $tz): static

Get a ChronosInterface instance for the current date and time

Parameters

DateTimeZone|string|null $tz: The DateTimeZone object or timezone name.

Returns

static

nthOfMonth() public

nthOfMonth(int $nth, int $dayOfWeek): mixed

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. static::MONDAY.

Parameters

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

Returns

mixed

nthOfQuarter() public

nthOfQuarter(int $nth, int $dayOfWeek): mixed

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. static::MONDAY.

Parameters

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

Returns

mixed

nthOfYear() public

nthOfYear(int $nth, int $dayOfWeek): mixed

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. static::MONDAY.

Parameters

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

Returns

mixed

parse() public static

parse(DateTimeInterface|string|int $time = 'now', DateTimeZone|string|null $tz = null): static

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

Parameters

DateTimeInterface|string|int $time optional: The strtotime compatible string to parse
DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name.

Returns

static

parseDate() public static

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

Returns a new Time object after parsing the provided $date 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.

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 = Time::parseDate('10/13/2013');
 $time = Time::parseDate('13 Oct, 2013', 'dd MMM, y');
 $time = Time::parseDate('13 Oct, 2013', IntlDateFormatter::SHORT);

Parameters

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

Returns

static|null

parseDateTime() public static

parseDateTime(string $time, array<int>|string|null $format = null, 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.

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

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|null $format optional: Any format accepted by IntlDateFormatter.
DateTimeZone|string|null $tz optional: The timezone for the instance

Returns

static|null

parseTime() public static

parseTime(string $time, string|int|null $format = 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.

When no $format is provided, the IntlDateFormatter::SHORT format will be used.

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

Example:

$time = Time::parseTime('11:23pm');

Parameters

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

Returns

static|null

previous() public

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

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. static::MONDAY.

Parameters

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

Returns

mixed

resetToStringFormat() public static

resetToStringFormat(): void

Resets the format used to the default when converting an instance of this type to a string

Returns

void

safeCreateDateTimeZone() protected static

safeCreateDateTimeZone(DateTimeZone|string|null $object): DateTimeZone

Creates a DateTimeZone from a string or a DateTimeZone

Parameters

DateTimeZone|string|null $object: The value to convert.

Returns

DateTimeZone

Throws

InvalidArgumentException

second() public

second(int $value): static

Set the instance's second

Parameters

int $value: The seconds value.

Returns

static

secondsSinceMidnight() public

secondsSinceMidnight(): int

The number of seconds since midnight.

Returns

int

secondsUntilEndOfDay() public

secondsUntilEndOfDay(): int

The number of seconds until 23:59:59.

Returns

int

setDate() public

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

Set the date to a different date.

Workaround for a PHP bug related to the first day of a month

Parameters

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

Returns

static

setDateTime() public

setDateTime(int $year, int $month, int $day, int $hour, int $minute, int $second = 0): static

Set the date and time all together

Parameters

int $year: The year to set.
int $month: The month to set.
int $day: The day to set.
int $hour: The hour to set.
int $minute: The minute to set.
int $second optional: The second to set.

Returns

static

setDefaultLocale() public static

setDefaultLocale(string|null $locale = null): void

Sets the default locale.

Set to null to use IntlDateFormatter default.

Parameters

string|null $locale optional: The default locale string to be used.

Returns

void

setDiffFormatter() public static

setDiffFormatter(Cake\Chronos\DifferenceFormatterInterface $formatter): void

Set the difference formatter instance.

Parameters

Cake\Chronos\DifferenceFormatterInterface $formatter: The formatter instance when setting.

Returns

void

setJsonEncodeFormat() public static

setJsonEncodeFormat(Closure|array|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 (https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html#details)

It is possible to provide an array of 2 constants. In this case, the first position will be used for formatting the date part of the object and the second position will be used to format the time part.

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

Parameters

Closure|array|string|int $format

Returns

void

setTestNow() public static

setTestNow(Cake\Chronos\ChronosInterface|string|null $testNow = null): void

Set a ChronosInterface instance (real or mock) to be returned when a "now" instance is created. The provided instance will be returned specifically under the following conditions:

A call to the static now() method, ex. ChronosInterface::now()
When a null (or blank string) is passed to the constructor or parse(), ex. new Chronos(null)
When the string "now" is passed to the constructor or parse(), ex. new Chronos('now')
When a string containing the desired time is passed to ChronosInterface::parse()

Note the timezone parameter was left out of the examples above and has no affect as the mock value will be returned regardless of its value.

To clear the test instance call this method using the default parameter of null.

Parameters

Cake\Chronos\ChronosInterface|string|null $testNow optional: The instance to use for all future instances.

Returns

void

setTimeFromTimeString() public

setTimeFromTimeString(string $time): static

Set the time by time string

Parameters

string $time: Time as string.

Returns

static

setTimezone() public

setTimezone(DateTimeZone|string $value): static

Set the instance's timezone from a string or object

Parameters

DateTimeZone|string $value: The DateTimeZone object or timezone name to use.

Returns

static

setToStringFormat() public static

setToStringFormat(string $format): void

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

Parameters

string $format: Format.

Returns

void

setWeekEndsAt() public static

setWeekEndsAt(int $day): void

Set the last day of week

Parameters

int $day: The day the week ends with.

Returns

void

setWeekStartsAt() public static

setWeekStartsAt(int $day): void

Set the first day of week

Parameters

int $day: The day the week starts with.

Returns

void

setWeekendDays() public static

setWeekendDays(array $days): void

Set weekend days

Parameters

array $days: Which days are 'weekends'.

Returns

void

startOfCentury() public

startOfCentury(): static

Resets the date to the first day of the century and the time to 00:00:00

Returns

static

startOfDay() public

startOfDay(): static

Resets the time to 00:00:00

Returns

static

startOfDecade() public

startOfDecade(): static

Resets the date to the first day of the decade and the time to 00:00:00

Returns

static

startOfMonth() public

startOfMonth(): static

Resets the date to the first day of the month and the time to 00:00:00

Returns

static

startOfWeek() public

startOfWeek(): static

Resets the date to the first day of week (defined in $weekStartsAt) and the time to 00:00:00

Returns

static

startOfYear() public

startOfYear(): static

Resets the date to the first day of the year and the time to 00:00:00

Returns

static

subDay() public

subDay(int $value = 1): static

Remove a day from the instance

Parameters

int $value optional: The number of days to remove.

Returns

static

subDays() public

subDays(int $value): static

Remove days from the instance

Parameters

int $value: The number of days to remove.

Returns

static

subHour() public

subHour(int $value = 1): static

Remove an hour from the instance

Parameters

int $value optional: The number of hours to remove.

Returns

static

subHours() public

subHours(int $value): static

Remove hours from the instance

Parameters

int $value: The number of hours to remove.

Returns

static

subMinute() public

subMinute(int $value = 1): static

Remove a minute from the instance

Parameters

int $value optional: The number of minutes to remove.

Returns

static

subMinutes() public

subMinutes(int $value): static

Remove minutes from the instance

Parameters

int $value: The number of minutes to remove.

Returns

static

subMonth() public

subMonth(int $value = 1): static

Remove a month from the instance

Has the same behavior as addMonths().

Parameters

int $value optional: The number of months to remove.

Returns

static

subMonthWithOverflow() public

subMonthWithOverflow(int $value = 1): static

Remove a month with overflow from the instance.

Has the same behavior as addMonthsWithOverflow().

Parameters

int $value optional: The number of months 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

Remove months with overflow from the instance.

Has the same behavior as addMonthsWithOverflow().

Parameters

int $value: The number of months to remove.

Returns

static

subSecond() public

subSecond(int $value = 1): static

Remove a second from the instance

Parameters

int $value optional: The number of seconds to remove.

Returns

static

subSeconds() public

subSeconds(int $value): static

Remove seconds from the instance

Parameters

int $value: The number of seconds to remove.

Returns

static

subWeek() public

subWeek(int $value = 1): static

Remove a week from the instance

Parameters

int $value optional: The number of weeks to remove.

Returns

static

subWeekday() public

subWeekday(int $value = 1): static

Remove a weekday from the instance

Parameters

int $value optional: The number of weekdays 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

subYear() public

subYear(int $value = 1): static

Remove a year from the instance.

Has the same behavior as addYears().

Parameters

int $value optional: The number of years to remove.

Returns

static

subYearWithOverflow() public

subYearWithOverflow(int $value = 1): static

Remove a year with overflow from the instance

Has the same behavior as addYearsWithOverflow().

Parameters

int $value optional: The number of years 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 addYearsWithOverflow().

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 time and this object.

Options:

from => another Time object representing the "now" time
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 "hour")
- hour => The format if hours > 0 (default "minute")
- minute => The format if minutes > 0 (default "minute")
- second => The format if seconds > 0 (default "second")
end => The end of relative time telling
relativeString => The printf compatible string when outputting relative time
absoluteString => The printf compatible string when outputting absolute time
timezone => The user timezone the timestamp should be formatted in.

Relative dates look something like this:

3 weeks, 4 days ago
15 seconds 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

timestamp() public

timestamp(int $value): static

Set the instance's timestamp

Parameters

int $value: The timestamp value to set.

Returns

static

timezone() public

timezone(DateTimeZone|string $value): static

Alias for setTimezone()

Parameters

DateTimeZone|string $value: The DateTimeZone object or timezone name to use.

Returns

static

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

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

toMutable() public

toMutable(): Cake\Chronos\MutableDateTime

Create a new mutable instance from current immutable instance.

Returns

Cake\Chronos\MutableDateTime

toQuarter() public

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

Returns the quarter

Parameters

bool $range optional: Range.

Returns

int|array

toRfc1036String() public

toRfc1036String(): string

Format the instance as RFC1036

Returns

string

toRfc1123String() public

toRfc1123String(): string

Format the instance as RFC1123

Returns

string

toRfc2822String() public

toRfc2822String(): string

Format the instance as RFC2822

Returns

string

toRfc3339String() public

toRfc3339String(): string

Format the instance as RFC3339

Returns

string

toRfc822String() public

toRfc822String(): string

Format the instance as RFC822

Returns

string

toRfc850String() public

toRfc850String(): string

Format the instance as RFC850

Returns

string

toRssString() public

toRssString(): string

Format the instance as RSS

Returns

string

toTimeString() public

toTimeString(): string

Format the instance as time

Returns

string

toUnixString() public

toUnixString(): string

Returns a UNIX timestamp.

Returns

string

toW3cString() public

toW3cString(): string

Format the instance as W3C

Returns

string

toWeek() public

toWeek(): int

Returns

int

today() public static

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

Create a ChronosInterface instance for today

Parameters

DateTimeZone|string|null $tz optional: The timezone to use.

Returns

static

tomorrow() public static

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

Create a ChronosInterface instance for tomorrow

Parameters

DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

tz() public

tz(DateTimeZone|string $value): static

Alias for setTimezone()

Parameters

DateTimeZone|string $value: The DateTimeZone object or timezone name to use.

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 $tz = null): static

Create a ChronosInterface instance for yesterday

Parameters

DateTimeZone|string|null $tz optional: The DateTimeZone object or timezone name the new instance should use.

Returns

static

Property Detail

`$day` public @property-read

Type

int

`$dayOfWeek` public @property-read

1 (for Monday) through 7 (for Sunday)

Type

int

`$dayOfWeekName` public @property-read

Type

int

`$lenientParsing` protected static

Whether lenient parsing is enabled for IntlDateFormatter.

Defaults to true which is the default for IntlDateFormatter.

Type

bool

`$local` public @property-read

checks if the timezone is local, true if local, false otherwise

Type

bool

`$micro` public @property-read

Type

int

`$microsecond` public @property-read

Type

int

`$minute` public @property-read

Type

int

`$month` public @property-read

int

`$testNow` protected static

A test ChronosInterface instance to be returned when now instances are created

Type

int

`$yearIso` public @property-read

Type

int

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.4/class-Cake.I18n.FrozenTime.html