Class Time
Extends time class provided by Chronos.
Adds handy methods and locale-aware formatting helpers.
Constants
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\Time::i18nFormat()
and__toString
. -
$formatters protected static
array<string, \IntlDateFormatter>
In-memory cache of date formatters
-
$niceFormat public static
string|int
The format to use when formatting a time using
Cake\I18n\Time::nice()
-
$ticks protected
int
-
$toStringFormat protected static
string
Format to use for __toString method.
Method Summary
-
__construct() public
Copies time from onther instance or from time string in the format HH[:.]mm or HH[:.]mm[:.]ss.u.
-
__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+
-
_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.
-
between() public
Returns whether time is between time range.
-
endOfDay() public static
Returns instance set to end of day - either 23:59:59 or 23:59:59.999999 if
$microseconds
is true -
equals() public
Returns whether time is equal to target time.
-
format() public
Formats string using the same syntax as
DateTimeImmutable::format()
. -
getHours() public
Returns clock hours.
-
getMicroseconds() public
Returns clock microseconds.
-
getMinutes() public
Returns clock minutes.
-
getSeconds() public
Return clock seconds.
-
greaterThan() public
Returns whether time is greater than target time.
-
greaterThanOrEquals() public
Returns whether time is greater than or equal to target time.
-
i18nFormat() public
Returns a formatted string for this time object using the preferred format and language for the specified locale.
-
jsonSerialize() public
Returns a string that should be serialized when converting this object to JSON
-
lessThan() public
Returns whether time is less than target time.
-
lessThanOrEquals() public
Returns whether time is less than or equal to target time.
-
midnight() public static
Returns instance set to midnight.
-
mod() protected static
-
nice() public
Returns a nicely formatted date string for this object.
-
noon() public static
Returns instance set to noon.
-
now() public static
Returns instance set to server time.
-
parse() public static
Copies time from onther instance or from string in the format HH[:.]mm or HH[:.]mm[:.]ss.u
-
parseString() protected static
-
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.
-
resetToStringFormat() public static
Resets the format used to the default when converting an instance of this type to a string
-
setHours() public
Set clock hours.
-
setJsonEncodeFormat() public static
Sets the default format used when converting this object to JSON
-
setMicroseconds() public
Sets clock microseconds.
-
setMinutes() public
Set clock minutes.
-
setSeconds() public
Set clock seconds.
-
setTime() public
Sets clock time.
-
setToStringFormat() public static
Sets the default format used when type converting instances of this type to string
-
toDateTimeImmutable() public
Returns an
DateTimeImmutable
instance set to this clock time. -
toNative() public
Returns an
DateTimeImmutable
instance set to this clock time.
Method Detail
__construct() ¶ public
__construct(Cake\Chronos\ChronosTime|DateTimeInterface|string|null $time = null, DateTimeZone|string|null $timezone = null)
Copies time from onther instance or from time string in the format HH[:.]mm or HH[:.]mm[:.]ss.u.
Defaults to server time.
Parameters
-
Cake\Chronos\ChronosTime|DateTimeInterface|string|null
$time optional Time
-
DateTimeZone|string|null
$timezone optional The timezone to use for now
__toString() ¶ public
__toString(): string
Format the instance as a string using the set 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
between() ¶ public
between(Cake\Chronos\ChronosTime $start, Cake\Chronos\ChronosTime $end, bool $equals = true): bool
Returns whether time is between time range.
Parameters
-
Cake\Chronos\ChronosTime
$start Start of target range
-
Cake\Chronos\ChronosTime
$end End of target range
-
bool
$equals optional Whether to include the beginning and end of range
Returns
bool
endOfDay() ¶ public static
endOfDay(bool $microseconds = false): static
Returns instance set to end of day - either
23:59:59 or 23:59:59.999999 if $microseconds
is true
Parameters
-
bool
$microseconds optional Whether to set microseconds or not
Returns
static
equals() ¶ public
equals(Cake\Chronos\ChronosTime $target): bool
Returns whether time is equal to target time.
Parameters
-
Cake\Chronos\ChronosTime
$target Target time
Returns
bool
format() ¶ public
format(string $format): string
Formats string using the same syntax as DateTimeImmutable::format()
.
As this uses DateTimeImmutable::format() to format the string, non-time formatters will still be interpreted. Be sure to escape those characters first.
Parameters
-
string
$format Format string
Returns
string
greaterThan() ¶ public
greaterThan(Cake\Chronos\ChronosTime $target): bool
Returns whether time is greater than target time.
Parameters
-
Cake\Chronos\ChronosTime
$target Target time
Returns
bool
greaterThanOrEquals() ¶ public
greaterThanOrEquals(Cake\Chronos\ChronosTime $target): bool
Returns whether time is greater than or equal to target time.
Parameters
-
Cake\Chronos\ChronosTime
$target Target time
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
$time = new Time('23:10:10');
$time->i18nFormat();
$time->i18nFormat(\IntlDateFormatter::FULL);
$time->i18nFormat("HH':'mm':'ss");
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
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');
$time->i18nFormat('de-DE');
$time->i18nFormat(\IntlDateFormatter::FULL, 'de-DE');
You can control the default locale used through DateTime::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 time should be displayed (e.g. pt-BR)
Returns
string|int
jsonSerialize() ¶ public
jsonSerialize(): string|int
Returns a string that should be serialized when converting this object to JSON
Returns
string|int
lessThan() ¶ public
lessThan(Cake\Chronos\ChronosTime $target): bool
Returns whether time is less than target time.
Parameters
-
Cake\Chronos\ChronosTime
$target Target time
Returns
bool
lessThanOrEquals() ¶ public
lessThanOrEquals(Cake\Chronos\ChronosTime $target): bool
Returns whether time is less than or equal to target time.
Parameters
-
Cake\Chronos\ChronosTime
$target Target time
Returns
bool
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 Time::$niceFormat
.
Parameters
-
string|null
$locale optional The locale name in which the date should be displayed (e.g. pt-BR)
Returns
string
now() ¶ public static
now(DateTimeZone|string|null $timezone = null): static
Returns instance set to server time.
Parameters
-
DateTimeZone|string|null
$timezone optional The timezone to use for now
Returns
static
parse() ¶ public static
parse(Cake\Chronos\ChronosTime|DateTimeInterface|string $time = null, DateTimeZone|string|null $timezone = null): static
Copies time from onther instance or from string in the format HH[:.]mm or HH[:.]mm[:.]ss.u
Defaults to server time.
Parameters
-
Cake\Chronos\ChronosTime|DateTimeInterface|string
$time optional Time
-
DateTimeZone|string|null
$timezone optional The timezone to use for now
Returns
static
parseString() ¶ protected static
parseString(string $time): int
Parameters
-
string
$time Time string in the format HH[:.]mm or HH[:.]mm[:.]ss.u
Returns
int
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
resetToStringFormat() ¶ public static
resetToStringFormat(): void
Resets the format used to the default when converting an instance of this type to a string
Returns
void
setHours() ¶ public
setHours(int $hours): static
Set clock hours.
Parameters
-
int
$hours Clock hours
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
See Also
setMicroseconds() ¶ public
setMicroseconds(int $microseconds): static
Sets clock microseconds.
Parameters
-
int
$microseconds Clock microseconds
Returns
static
setMinutes() ¶ public
setMinutes(int $minutes): static
Set clock minutes.
Parameters
-
int
$minutes Clock minutes
Returns
static
setSeconds() ¶ public
setSeconds(int $seconds): static
Set clock seconds.
Parameters
-
int
$seconds Clock seconds
Returns
static
setTime() ¶ public
setTime(int $hours = 0, int $minutes = 0, int $seconds = 0, int $microseconds = 0): static
Sets clock time.
Parameters
-
int
$hours optional Clock hours
-
int
$minutes optional Clock minutes
-
int
$seconds optional Clock seconds
-
int
$microseconds optional Clock microseconds
Returns
static
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
toDateTimeImmutable() ¶ public
toDateTimeImmutable(DateTimeZone|string|null $timezone = null): DateTimeImmutable
Returns an DateTimeImmutable
instance set to this clock time.
Parameters
-
DateTimeZone|string|null
$timezone optional Time zone the DateTimeImmutable instance will be in
Returns
DateTimeImmutable
toNative() ¶ public
toNative(DateTimeZone|string|null $timezone = null): DateTimeImmutable
Returns an DateTimeImmutable
instance set to this clock time.
Alias of toDateTimeImmutable()
.
Parameters
-
DateTimeZone|string|null
$timezone optional Time zone the DateTimeImmutable instance will be in
Returns
DateTimeImmutable
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\Time::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
$formatters ¶ protected static
In-memory cache of date formatters
Type
array<string, \IntlDateFormatter>
$niceFormat ¶ public static
The format to use when formatting a time using Cake\I18n\Time::nice()
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