Class TimeHelper

Time Helper class for easy use of time data.

Manipulation of time data.

Namespace: Cake\View\Helper
See: \Cake\I18n\Time
Link: https://book.cakephp.org/3/en/views/helpers/time.html

Property Summary

$_View protected

Cake\View\View

The View instance this helper is attached to
$_config protected

array

Runtime config
$_configInitialized protected

bool

Whether the config property has already been configured with defaults
$_defaultConfig protected

array

Config options
$_helperMap protected

array

A helper lookup table used to lazy load helper objects.
$_templater protected

Cake\View\StringTemplate

StringTemplate instance.
$fieldset public deprecated

array

Unused.
$helpers protected

array

List of helpers used by this helper
$tags public deprecated

array

Unused.

Method Summary

__call() public

Provide non fatal errors on missing method calls.
__construct() public

Default Constructor
__debugInfo() public

Returns an array that can be used to describe the internal state of this object.
__get() public

Lazy loads helpers.
__set() public

Magic setter for removed properties.
_cleanConfirmMessage() protected

Returns a string read to be used in confirm()
_configDelete() protected

Deletes a single config key.
_configRead() protected

Reads a config key.
_configWrite() protected

Writes a config key.
_confirm() protected

Returns a string to be used as onclick handler for confirm dialogs.
_getTimezone() protected

Get a timezone.
addClass() public

Adds the given class to the element options
config() public deprecated

Gets/Sets the config.
configShallow() public

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.
format() public

Returns a formatted date string, given either a Time instance, UNIX timestamp or a valid strtotime() date string.
formatTemplate() public

Formats a template string with $data
fromString() public

Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.
getConfig() public

Returns the config.
getConfigOrFail() public

Returns the config for this specific key.
getTemplates() public

Gets templates to use or a specific template.
getView() public

Get the view instance this helper is bound to.
gmt() public

Returns gmt as a UNIX timestamp.
i18nFormat() public

Returns a formatted date string, given either a Datetime instance, UNIX timestamp or a valid strtotime() date string.
implementedEvents() public

Event listeners.
initialize() public

Constructor hook method.
isFuture() public

Returns true, if the given datetime string is in the future.
isPast() public

Returns true, if the given datetime string is in the past.
isThisMonth() public

Returns true if given datetime string is within this month
isThisWeek() public

Returns true if given datetime string is within this week.
isThisYear() public

Returns true if given datetime string is within the current year.
isToday() public

Returns true, if the given datetime string is today.
isTomorrow() public

Returns true if given datetime string is tomorrow.
isWithinNext() public

Returns true if specified datetime is within the interval specified, else false.
nice() public

Returns a nicely formatted date string for given Datetime string.
setConfig() public

Sets the config.
setTemplates() public

Sets templates to use.
templater() public

Returns the templater instance.
templates() public deprecated

Gets/sets templates to use.
timeAgoInWords() public

Formats a date into a phrase expressing the relative time.
toAtom() public

Returns a date formatted for Atom RSS feeds.
toQuarter() public

Returns the quarter
toRss() public

Formats date for RSS feeds
toUnix() public

Returns a UNIX timestamp from a textual datetime description.
wasWithinLast() public

Returns true if specified datetime was within the interval specified, else false.
wasYesterday() public

Returns true if given datetime string was yesterday.

Method Detail

__call() ¶ public

__call(string $method, array $params): mixed|void

Provide non fatal errors on missing method calls.

Parameters

string $method: Method to invoke
array $params: Array of params for the method.

Returns

mixed|void

__construct() ¶ public

__construct(Cake\View\View $View, array $config = [])

Default Constructor

Parameters

Cake\View\View $View: The View this helper is being attached to.
array $config optional: Configuration settings for the helper.

__debugInfo() ¶ public

__debugInfo(): array

Returns an array that can be used to describe the internal state of this object.

Returns

array

__get() ¶ public

__get(string $name): Cake\View\Helper|null

Lazy loads helpers.

Parameters

string $name: Name of the property being accessed.

Returns

Cake\View\Helper|null

Helper instance if helper with provided name exists

__set() ¶ public

__set(string $name, mixed $value): void

Magic setter for removed properties.

Parameters

string $name: Property name.
mixed $value: Value to set.

Returns

void

_cleanConfirmMessage() ¶ protected

_cleanConfirmMessage(string $message): mixed

Returns a string read to be used in confirm()

Parameters

string $message: The message to clean

Returns

mixed

_configDelete() ¶ protected

_configDelete(string $key): void

Deletes a single config key.

Parameters

string $key: Key to delete.

Returns

void

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() ¶ protected

_configRead(string|null $key): mixed

Reads a config key.

Parameters

string|null $key: Key to read.

Returns

mixed

_configWrite() ¶ protected

_configWrite(string|array $key, mixed $value, bool|string $merge = false): void

Writes a config key.

Parameters

string|array $key: Key to write to.
mixed $value: Value to write.
bool|string $merge optional: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Returns

void

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_confirm() ¶ protected

_confirm(string $message, string $okCode, string $cancelCode = '', array $options = []): string

Returns a string to be used as onclick handler for confirm dialogs.

Parameters

string $message: Message to be displayed
string $okCode: Code to be executed after user chose 'OK'
string $cancelCode optional: Code to be executed after user chose 'Cancel'
array $options optional: Array of options

Returns

string

onclick JS code

_getTimezone() ¶ protected

_getTimezone(DateTimeZone|string|null $timezone): DateTimeZone|string|null

Get a timezone.

Will use the provided timezone, or default output timezone if defined.

Parameters

DateTimeZone|string|null $timezone: The override timezone if applicable.

Returns

DateTimeZone|string|null

The chosen timezone or null.

addClass() ¶ public

addClass(array $options = [], string|null $class = null, string $key = 'class'): array

Adds the given class to the element options

Parameters

array $options optional: Array options/attributes to add a class to
string|null $class optional: The class name being added.
string $key optional: the key to use for class. Defaults to 'class'.

Returns

array

Array of options with $key set.

config() ¶ public

config(string|array|null $key = null, mixed|null $value = null, bool $merge = true): mixed

Gets/Sets the config.

Usage

Reading the whole config:

$this->config();

Reading a specific value:

$this->config('key');

Reading a nested value:

$this->config('some.nested.key');

Setting a specific value:

$this->config('key', $value);

Setting a nested value:

$this->config('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->config(['one' => 'value', 'another' => 'value']);

Parameters

string|array|null $key optional: The key to get/set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

mixed

Config value being read, or the object itself on write operations.

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

configShallow() ¶ public

configShallow(string|array $key, mixed|null $value = null): $this

Merge provided config with existing config. Unlike config() which does a recursive merge for nested keys, this method does a simple merge.

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.

Returns

$this

format() ¶ public

format(int|string|DateTime $date, int|string|null $format = null, string|false $invalid = false, string|DateTimeZone|null $timezone = null): string|int|false

Returns a formatted date string, given either a Time instance, UNIX timestamp or a valid strtotime() date string.

This method is an alias for TimeHelper::i18nFormat().

Parameters

int|string|DateTime $date: UNIX timestamp, strtotime() valid string or DateTime object (or a date format string).
int|string|null $format optional: date format string (or a UNIX timestamp, strtotime() valid string or DateTime object).
string|false $invalid optional: Default value to display on invalid dates
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

string|int|false

Formatted and translated date string

formatTemplate() ¶ public

formatTemplate(string $name, array $data): string

Formats a template string with $data

Parameters

string $name: The template name.
array $data: The data to insert.

Returns

string

fromString() ¶ public

fromString(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): Cake\I18n\Time

Returns a UNIX timestamp, given either a UNIX timestamp or a valid strtotime() date string.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

Cake\I18n\Time

getConfig() ¶ public

getConfig(string|null $key = null, mixed|null $default = null): mixed|null

Returns the config.

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

string|null $key optional: The key to get or null for the whole config.
mixed|null $default optional: The return value when the key does not exist.

Returns

mixed|null

Configuration data at the named key or null if the key does not exist.

getConfigOrFail() ¶ public

getConfigOrFail(string|null $key): mixed

Returns the config for this specific key.

The config value for this key must exist, it can never be null.

Parameters

string|null $key: The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getTemplates() ¶ public

getTemplates(string|null $template = null): string|array

Gets templates to use or a specific template.

Parameters

string|null $template optional: String for reading a specific template, null for all.

Returns

string|array

getView() ¶ public

getView(): Cake\View\View

Get the view instance this helper is bound to.

Returns

Cake\View\View

The bound view instance.

gmt() ¶ public

gmt(int|string|DateTime|null $string = null): string

Returns gmt as a UNIX timestamp.

Parameters

int|string|DateTime|null $string optional: UNIX timestamp, strtotime() valid string or DateTime object

Returns

string

UNIX timestamp

i18nFormat() ¶ public

i18nFormat(int|string|DateTimeInterface|null $date, string|int|null $format = null, string|false $invalid = false, string|DateTimeZone|null $timezone = null): string|int|false

Returns a formatted date string, given either a Datetime instance, UNIX timestamp or a valid strtotime() date string.

Parameters

int|string|DateTimeInterface|null $date: UNIX timestamp, strtotime() valid string or DateTime object
string|int|null $format optional: Intl compatible format string.
string|false $invalid optional: Default value to display on invalid dates
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

string|int|false

Formatted and translated date string or value for $invalid on failure.

Throws

Exception
When the date cannot be parsed

implementedEvents() ¶ public

implementedEvents(): array

Event listeners.

By defining one of the callback methods a helper is assumed to be interested in the related event.

Override this method if you need to add non-conventional event listeners. Or if you want helpers to listen to non-standard events.

Returns

array

initialize() ¶ public

initialize(array $config): void

Constructor hook method.

Implement this method to avoid having to overwrite the constructor and call parent.

Parameters

array $config: The configuration settings provided to this helper.

Returns

void

isFuture() ¶ public

isFuture(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true, if the given datetime string is in the future.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if the given datetime string lies in the future.

isPast() ¶ public

isPast(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true, if the given datetime string is in the past.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if the given datetime string lies in the past.

isThisMonth() ¶ public

isThisMonth(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if given datetime string is within this month

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if datetime string is within the current month

isThisWeek() ¶ public

isThisWeek(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if given datetime string is within this week.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if datetime string is within current week

isThisYear() ¶ public

isThisYear(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if given datetime string is within the current year.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if datetime string is within current year

isToday() ¶ public

isToday(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true, if the given datetime string is today.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if the given datetime string is today.

isTomorrow() ¶ public

isTomorrow(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if given datetime string is tomorrow.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if datetime string was yesterday

isWithinNext() ¶ public

isWithinNext(string|int $timeInterval, int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if specified datetime is within the interval specified, else false.

Parameters

string|int $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute. Integer input values are deprecated and support will be removed in 4.0.0
int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

nice() ¶ public

nice(int|string|DateTime|null $dateString = null, string|DateTimeZone|null $timezone = null, string|null $locale = null): string

Returns a nicely formatted date string for given Datetime string.

Parameters

int|string|DateTime|null $dateString optional: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object
string|null $locale optional: Locale string.

Returns

string

Formatted date string

setConfig() ¶ public

setConfig(string|array $key, mixed|null $value = null, bool $merge = true): $this

Sets the config.

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

string|array $key: The key to set, or a complete array of configs.
mixed|null $value optional: The value to set.
bool $merge optional: Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

setTemplates() ¶ public

setTemplates(string[] $templates): $this

Sets templates to use.

Parameters

string[] $templates: Templates to be added.

Returns

$this

templater() ¶ public

templater(): Cake\View\StringTemplate

Returns the templater instance.

Returns

Cake\View\StringTemplate

templates() ¶ public

templates(string|array|null $templates = null): $this|string|array

Gets/sets templates to use.

Parameters

string|array|null $templates optional: null or string allow reading templates. An array allows templates to be added.

Returns

$this|string|array

timeAgoInWords() ¶ public

timeAgoInWords(int|string|DateTime|Cake\Chronos\ChronosInterface $dateTime, array $options = []): string

Formats a date into a phrase expressing the relative time.

Additional options

element - The element to wrap the formatted time in. Has a few additional options:
- tag - The tag to use, defaults to 'span'.
- class - The class name to use, defaults to time-ago-in-words.
- title - Defaults to the $dateTime input.

Parameters

int|string|DateTime|Cake\Chronos\ChronosInterface $dateTime: UNIX timestamp, strtotime() valid string or DateTime object
array $options optional: Default format if timestamp is used in $dateString

Returns

string

Relative time string.

toAtom() ¶ public

toAtom(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): string

Returns a date formatted for Atom RSS feeds.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

string

Formatted date string

toQuarter() ¶ public

toQuarter(int|string|DateTime $dateString, bool $range = false): string[]|int

Returns the quarter

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
bool $range optional: if true returns a range in Y-m-d format

Returns

string[]|int

1, 2, 3, or 4 quarter of year or array if $range true

toRss() ¶ public

toRss(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): string

Formats date for RSS feeds

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

string

Formatted date string

toUnix() ¶ public

toUnix(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): string

Returns a UNIX timestamp from a textual datetime description.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

string

UNIX timestamp

wasWithinLast() ¶ public

wasWithinLast(string|int $timeInterval, int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if specified datetime was within the interval specified, else false.

Parameters

string|int $timeInterval: the numeric value with space then time type. Example of valid types: 6 hours, 2 days, 1 minute. Integer input values are deprecated and support will be removed in 4.0.0
int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

wasYesterday() ¶ public

wasYesterday(int|string|DateTime $dateString, string|DateTimeZone|null $timezone = null): bool

Returns true if given datetime string was yesterday.

Parameters

int|string|DateTime $dateString: UNIX timestamp, strtotime() valid string or DateTime object
string|DateTimeZone|null $timezone optional: User's timezone string or DateTimeZone object

Returns

bool

True if datetime string was yesterday

array

Namespaces

Class TimeHelper

Property Summary

Method Summary

__call() public

__construct() public

__debugInfo() public

__get() public

__set() public

_cleanConfirmMessage() protected

_configDelete() protected

_configRead() protected

_configWrite() protected

_confirm() protected

_getTimezone() protected

addClass() public

config() public deprecated

configShallow() public

format() public

formatTemplate() public

fromString() public

getConfig() public

getConfigOrFail() public

getTemplates() public

getView() public

gmt() public

i18nFormat() public

implementedEvents() public

initialize() public

isFuture() public

isPast() public

isThisMonth() public

isThisWeek() public

isThisYear() public

isToday() public

isTomorrow() public

isWithinNext() public

nice() public

setConfig() public

setTemplates() public

templater() public

templates() public deprecated

timeAgoInWords() public

toAtom() public

toQuarter() public

toRss() public

toUnix() public

wasWithinLast() public

wasYesterday() public

Method Detail

__call() ¶ public

Parameters

Returns

__construct() ¶ public

Parameters

__debugInfo() ¶ public

Returns

__get() ¶ public

Parameters

Returns

__set() ¶ public

Parameters

Returns

_cleanConfirmMessage() ¶ protected

Parameters

Returns

_configDelete() ¶ protected

Parameters

Returns

Throws

_configRead() ¶ protected

Parameters

Returns

_configWrite() ¶ protected

Parameters

Returns

Throws

_confirm() ¶ protected

Parameters

Returns