Fr3nch13/CakePHP Utilities

DateFormatTrait

Trait for date formatting methods shared by both Time & Date.

This trait expects that the implementing class define static::$_toStringFormat.

Properties

$_formatters : array<string|int, IntlDateFormatter>: In-memory cache of date formatters
$defaultLocale : string|null: The default locale to be used for displaying formatted date strings.
$lenientParsing : bool: Whether lenient parsing is enabled for IntlDateFormatter.

Methods

__debugInfo() : array<string, mixed>: Returns the data that should be displayed when debugging this object
__toString() : string
diffForHumans() : string: Get the difference in a human readable format.
disableLenientParsing() : void: Enables lenient parsing for locale formats.
enableLenientParsing() : void: Enables lenient parsing for locale formats.
getDefaultLocale() : string|null: Gets the default locale.
getDiffFormatter() : DifferenceFormatterInterface: Get the difference formatter instance.
i18nFormat() : string|int: Returns a formatted string for this time object using the preferred format and language for the specified locale.
jsonSerialize() : string|int: Returns a string that should be serialized when converting this object to JSON
lenientParsingEnabled() : bool: Gets whether locale format parsing is set to lenient.
nice() : string: Returns a nicely formatted date string for this object.
parseDate() : 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.
parseDateTime() : 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.
parseTime() : 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.
resetToStringFormat() : void: Resets the format used to the default when converting an instance of this type to a string
setDefaultLocale() : void: Sets the default locale.
setDiffFormatter() : void: Set the difference formatter instance.
setJsonEncodeFormat() : void
setToStringFormat() : void: Sets the default format used when type converting instances of this type to string
_formatObject() : string: Returns a translated and localized date string.

$_formatters

In-memory cache of date formatters


    protected
    static    array<string|int, IntlDateFormatter>
    $_formatters
     = []

$defaultLocale

The default locale to be used for displaying formatted date strings.


    protected
    static    string|null
    $defaultLocale

Use static::setDefaultLocale() and static::getDefaultLocale() instead.

$lenientParsing

Whether lenient parsing is enabled for IntlDateFormatter.


    protected
    static    bool
    $lenientParsing
     = true

Defaults to true which is the default for IntlDateFormatter.

__debugInfo()

Returns the data that should be displayed when debugging this object


    public
                    __debugInfo() : array<string, mixed>

Return values

array<string, mixed>

__toString()


    public
                    __toString() : string

Return values

string

diffForHumans()

Get the difference in a human readable format.


    public
                    diffForHumans([ChronosInterface|null $other = null ][, bool $absolute = false ]) : string

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

$other : ChronosInterface|null = null: The datetime to compare with.
$absolute : bool = false: removes time difference modifiers ago, after, etc

Return values

string

disableLenientParsing()

Enables lenient parsing for locale formats.


    public
            static        disableLenientParsing() : void

enableLenientParsing()

Enables lenient parsing for locale formats.


    public
            static        enableLenientParsing() : void

getDefaultLocale()

Gets the default locale.


    public
            static        getDefaultLocale() : string|null

Return values

string|null —

The default locale string to be used or null.

getDiffFormatter()

Get the difference formatter instance.


    public
            static        getDiffFormatter() : DifferenceFormatterInterface

Return values

DifferenceFormatterInterface

i18nFormat()

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


    public
                    i18nFormat([array<string|int, int>|string|int|null $format = null ][, DateTimeZone|string|null $timezone = null ][, string|null $locale = null ]) : string|int

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

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

Return values

string|int —

Formatted and translated date string

jsonSerialize()

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


    public
                    jsonSerialize() : string|int

#[ReturnTypeWillChange]

Return values

string|int

lenientParsingEnabled()

Gets whether locale format parsing is set to lenient.


    public
            static        lenientParsingEnabled() : bool

Return values

bool

nice()

Returns a nicely formatted date string for this object.


    public
                    nice([DateTimeZone|string|null $timezone = null ][, string|null $locale = null ]) : string

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

Parameters

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

Return values

string —

Formatted date string

parseDate()

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.


    public
            static        parseDate(string $date[, array<string|int, mixed>|string|int|null $format = null ]) : static|null

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

$date : string: The date string to parse.
$format : array<string|int, mixed>|string|int|null = null: Any format accepted by IntlDateFormatter.

Return values

static|null

parseDateTime()

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.


    public
            static        parseDateTime(string $time[, array<string|int, int>|string|int|null $format = null ][, DateTimeZone|string|null $tz = null ]) : static|null

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

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

Return values

static|null

parseTime()

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.


    public
            static        parseTime(string $time[, string|int|null $format = null ]) : static|null

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

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

Return values

static|null

resetToStringFormat()

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


    public
            static        resetToStringFormat() : void

setDefaultLocale()

Sets the default locale.


    public
            static        setDefaultLocale([string|null $locale = null ]) : void

Set to null to use IntlDateFormatter default.

Parameters

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

setDiffFormatter()

Set the difference formatter instance.


    public
            static        setDiffFormatter(DifferenceFormatterInterface $formatter) : void

Parameters

$formatter : DifferenceFormatterInterface: The formatter instance when setting.

setJsonEncodeFormat()


    public
            static        setJsonEncodeFormat(mixed $format) : void

Parameters

$format : mixed

setToStringFormat()

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


    public
            static        setToStringFormat(array<string|int, int>|string|int $format) : void

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.

Parameters

$format : array<string|int, int>|string|int: Format.

_formatObject()

Returns a translated and localized date string.


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

Implements what IntlDateFormatter::formatObject() is in PHP 5.5+

Parameters

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

Return values

string

DateFormatTrait

Table of Contents

Properties

Methods

Properties

$_formatters

$defaultLocale

$lenientParsing

Methods

__debugInfo()

Return values

__toString()

Tags

Return values

diffForHumans()

Parameters

Return values

disableLenientParsing()

enableLenientParsing()

getDefaultLocale()

Return values

getDiffFormatter()

Return values

i18nFormat()

Examples

Examples

Parameters

Return values

jsonSerialize()

Attributes

Return values

lenientParsingEnabled()

Return values

nice()

Parameters

Return values

parseDate()

Parameters

Return values

parseDateTime()

Parameters

Return values

parseTime()

Parameters

Return values

resetToStringFormat()

setDefaultLocale()

Parameters

setDiffFormatter()

Parameters

setJsonEncodeFormat()

Parameters

Tags

setToStringFormat()

Parameters

_formatObject()

Parameters

Return values