Class Time

Extends time class provided by Chronos.

Adds handy methods and locale-aware formatting helpers.

Namespace: Cake\I18n

Constants

string

DEFAULT_TO_STRING_FORMAT ¶
```
'H:i:s'
```
Default format to use for __toString method.
int

TICKS_PER_DAY ¶
```
self::TICKS_PER_HOUR * 24
```
int

TICKS_PER_HOUR ¶
```
self::TICKS_PER_MINUTE * 60
```
int

TICKS_PER_MICROSECOND ¶
```
1
```
int

TICKS_PER_MINUTE ¶
```
self::TICKS_PER_SECOND * 60
```
int

TICKS_PER_SECOND ¶
```
1000000
```

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

getHours() ¶ public

getHours(): int

Returns clock hours.

Returns

int

getMicroseconds() ¶ public

getMicroseconds(): int

Returns clock microseconds.

Returns

int

getMinutes() ¶ public

getMinutes(): int

Returns clock minutes.

Returns

int

getSeconds() ¶ public

getSeconds(): int

Return clock seconds.

Returns

int

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

Formatted and translated time string

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

midnight() ¶ public static

midnight(): static

Returns instance set to midnight.

Returns

static

mod() ¶ protected static

mod(int $a, int $b): int

Parameters

int $a: Right side
int $b

Returns

int

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

Formatted date string

noon() ¶ public static

noon(): static

Returns instance set to noon.

Returns

static

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

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

`$ticks` ¶ protected

Type

int

`$toStringFormat` ¶ protected static

Format to use for __toString method.

Type

string

Namespaces

Class Time

Constants

Property Summary

Method Summary

__construct() public

__toString() public

_formatObject() protected

_parseDateTime() protected static

between() public

endOfDay() public static

equals() public

format() public

getHours() public

getMicroseconds() public

getMinutes() public

getSeconds() public

greaterThan() public

greaterThanOrEquals() public

i18nFormat() public

jsonSerialize() public

lessThan() public

lessThanOrEquals() public

midnight() public static

mod() protected static

nice() public

noon() public static

now() public static

parse() public static

parseString() protected static

parseTime() public static

resetToStringFormat() public static

setHours() public

setJsonEncodeFormat() public static

setMicroseconds() public

setMinutes() public

setSeconds() public

setTime() public

setToStringFormat() public static

toDateTimeImmutable() public

toNative() public

Method Detail

__construct() ¶ public

Parameters

__toString() ¶ public

Returns

_formatObject() ¶ protected

Parameters

Returns

_parseDateTime() ¶ protected static

Parameters

Returns

between() ¶ public

Parameters

Returns

endOfDay() ¶ public static

Parameters

Returns

equals() ¶ public

Parameters

Returns

format() ¶ public

Parameters

Returns

getHours() ¶ public

Returns

getMicroseconds() ¶ public

Returns

getMinutes() ¶ public

Returns

getSeconds() ¶ public

Returns

greaterThan() ¶ public

Parameters

Returns

greaterThanOrEquals() ¶ public

Parameters

Returns

i18nFormat() ¶ public

Examples

`$_jsonEncodeFormat` ¶ protected static