1. class
  2. Concrete
  3. \
  4. Core
  5. \
  6. Localization
  7. \
  8. Service
  9. \
  10. Date

Date

class Date (View source)

Constants

DB_FORMAT

The PHP date/time format string to be used when dealing with the database.

Methods

string
toDB(string|int|DateTime $value = 'now', string $fromTimezone = 'system')

Convert any date/time representation to a string that can be used in DB queries.

string|int
getOverridableNow(bool $asTimestamp = false)

Return the date/time representation for now, that can be overridden by a custom request when viewing pages in a moment specified by administrators (custom request date/time).

string
date(string $mask, bool|int $timestamp = false, string $toTimezone = 'system')

Subsitute for the native date() function that adds localized date support.

string
getTimezoneName(string $timezoneID)

Retrieve the display name (localized) of a time zone given its PHP identifier.

array
getTimezones()

Returns a keyed array of timezone identifiers (keys are the standard PHP timezone names, values are the localized timezone names).

array
getGroupedTimezones()

Returns the list of timezones with translated names, grouped by region.

string
getTimezoneDisplayName(string|DateTimeZone|DateTime $timezone)

Returns the display name of a timezone.

string
timeSince(int $posttime, bool $precise = false)

Describe the difference in time between now and a date/time in the past.

string
describeInterval(int $diff, bool $precise = false)

Returns the localized representation of a time interval specified as seconds.

string
getTimezoneID(string $timezone)

Returns the normalized timezone identifier.

string
getUserTimeZoneID()

No description

DateTimeZone|null
getTimezone(string $timezone)

Returns a \DateTimeZone instance for a specified timezone identifier.

DateTime|null
toDateTime(string|DateTime|int $value = 'now', string $toTimezone = 'system', string $fromTimezone = 'system')

Convert a date to a \DateTime instance.

int|null
getDeltaDays(mixed $from, mixed $to, string $timezone = 'user')

Returns the difference in days between to dates.

string
formatDate(mixed $value = 'now', string $format = 'short', string $toTimezone = 'user')

Render the date part of a date/time as a localized string.

string
formatTime(mixed $value = 'now', bool $withSeconds = false, string $toTimezone = 'user')

Render the time part of a date/time as a localized string.

string
formatDateTime(mixed $value = 'now', bool $longDate = false, bool $withSeconds = false, string $toTimezone = 'user')

Render both the date and time parts of a date/time as a localized string.

string
formatPrettyDate(mixed $value, bool $longDate = false, string $toTimezone = 'user')

Render the date part of a date/time as a localized string. If the day is yesterday we'll print 'Yesterday' (the same for today, tomorrow).

string
formatPrettyDateTime(mixed $value, bool $longDate = false, bool $withSeconds = false, string $timezone = 'user')

Render both the date and time parts of a date/time as a localized string. If the day is yesterday we'll print 'Yesterday' (the same for today, tomorrow).

string
formatCustom(string $format, mixed $value = 'now', string $toTimezone = 'user', string $fromTimezone = 'system')

Render a date/time as a localized string, by specifying a custom format.

string
getJQueryUIDatePickerFormat(string $relatedPHPFormat = '')

Returns the format string for the jQueryUI DatePicker widget

int
getTimeFormat()

Returns the time format (12 or 24).

string
getPHPDatePattern()

No description

string
getPHPTimePattern()

Get the PHP date format string for times.

string
getPHPDateTimePattern()

Get the PHP date format string for dates/times.

getLocalDateTime($systemDateTime = 'now', $mask = null) deprecated

No description

getSystemDateTime($userDateTime = 'now', $mask = null) deprecated

No description

dateTimeFormatLocal($datetime, $mask) deprecated

No description

Details

at line 49
string toDB(string|int|DateTime $value = 'now', string $fromTimezone = 'system')

Convert any date/time representation to a string that can be used in DB queries.

Parameters

string|int|DateTime $value

It can be:

  • the special value 'now' (default) to return the current date/time
  • a \DateTime instance
  • a string parsable by strtotime (the $fromTimezone timezone is used)
  • a timestamp
string $fromTimezone

The timezone where $value is defined (useful only if $value is a date/time representation without a timezone, like for instance '2000-12-31 23:59:59').
Special values are:

  • 'system' (default) for the current system timezone
  • 'user' for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )

Return Value

string

Exceptions

BadArgumentType

at line 63
string|int getOverridableNow(bool $asTimestamp = false)

Return the date/time representation for now, that can be overridden by a custom request when viewing pages in a moment specified by administrators (custom request date/time).

Parameters

bool $asTimestamp

Set to true to retrieve the Unix timestamp, false to retrieve the string representation (eg '2000-12-31 23:59:59')

Return Value

string|int

at line 96
string date(string $mask, bool|int $timestamp = false, string $toTimezone = 'system')

Subsitute for the native date() function that adds localized date support.

Use ONLY if really needed: you may want to use some of the formatDate/Time methods. If you're not working with timestamps you may want to use the formatCustom method.

Parameters

string $mask

The PHP format mask
bool|int $timestamp

Use false for the current date/time, otherwise a valid Unix timestamp (we assume it's in the system timezone)
string $toTimezone

The destination timezone.
Special values are:

  • 'system' (default) for the current system timezone
  • 'user' for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )

Return Value

string

Exceptions

Exception

See also

http://php.net/manual/function.date.php

at line 124
string getTimezoneName(string $timezoneID)

Retrieve the display name (localized) of a time zone given its PHP identifier.

Parameters

string $timezoneID

Return Value

string

at line 142
array getTimezones()

Returns a keyed array of timezone identifiers (keys are the standard PHP timezone names, values are the localized timezone names).

Return Value

array

See also

http://www.php.net/datetimezone.listidentifiers.php

at line 280
array getGroupedTimezones()

Returns the list of timezones with translated names, grouped by region.

Return Value

array

See also

http://www.php.net/datetimezone.listidentifiers.php

Examples

<pre>[
   'Africa' => [
       'Africa/Abidjan' => 'Abidjan',
       'Africa/Addis_Ababa' => 'Addis Abeba',
   ],
   'Americas' => [
       'America/North_Dakota/Beulah' => 'Beulah, North Dakota',
   ],
   'Antarctica' => [
       'Antarctica/McMurdo' => 'McMurdo',
   ],
   'Arctic' => [
       ...
   ],
   'Asia' => [
       ....
   ],
   'Atlantic Ocean' => [
       ....
   ],
   'Australia' => [
       ....
   ],
   'Europe' => [
       ....
   ],
   'Indian Ocean' => [
       ....
   ],
   'Pacific Ocean' => [
       ....
   ],
   'Others' => [
       'UTC' => 'Greenwich Mean Time (UTC)',
   ],
]</pre>

at line 314
string getTimezoneDisplayName(string|DateTimeZone|DateTime $timezone)

Returns the display name of a timezone.

Parameters

string|DateTimeZone|DateTime $timezone

The timezone for which you want the localized display name

Return Value

string

at line 347
string timeSince(int $posttime, bool $precise = false)

Describe the difference in time between now and a date/time in the past.

If the date/time is in the future or if it's more than one year old, you'll get the date representation of $posttime.

Parameters

int $posttime

The timestamp to analyze
bool $precise

= false Set to true to a more verbose and precise result, false for a more rounded result

Return Value

string

Exceptions

Exception

at line 365
string describeInterval(int $diff, bool $precise = false)

Returns the localized representation of a time interval specified as seconds.

Parameters

int $diff

The time difference in seconds
bool $precise

= false Set to true to a more verbose and precise result, false for a more rounded result

Return Value

string

at line 411
string getTimezoneID(string $timezone)

Returns the normalized timezone identifier.

Parameters

string $timezone

The timezone to retrieve. Special values are:

  • 'system' (default) for the current system timezone
  • 'user' for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )

Return Value

string

at line 458
string getUserTimeZoneID()

No description

Return Value

string

at line 475
DateTimeZone|null getTimezone(string $timezone)

Returns a \DateTimeZone instance for a specified timezone identifier.

Parameters

string $timezone

The timezone to retrieve. Special values are:

  • 'system' (default) for the current system timezone
  • 'user' for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )

Return Value

DateTimeZone|null

Returns null if $timezone is invalid or the \DateTimeZone corresponding to $timezone

at line 510
DateTime|null toDateTime(string|DateTime|int $value = 'now', string $toTimezone = 'system', string $fromTimezone = 'system')

Convert a date to a \DateTime instance.

Parameters

string|DateTime|int $value

It can be:

  • the special value 'now' (default) to return the current date/time
  • a \DateTime instance
  • a string parsable by strtotime (the $fromTimezone timezone is used)
  • a timestamp
string $toTimezone

The timezone to set. Special values are:

  • 'system' (default) for the current system timezone
  • 'user' for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )
string $fromTimezone

The original timezone of $value (useful only if $value is a string like '2000-12-31 23:59'); it accepts the same values as $toTimezone

Return Value

DateTime|null

Returns the \DateTime instance (or null if $value couldn't be parsed)

Exceptions

BadArgumentType

at line 532
int|null getDeltaDays(mixed $from, mixed $to, string $timezone = 'user')

Returns the difference in days between to dates.

Parameters

mixed $from

The start date/time representation (one of the values accepted by toDateTime)
mixed $to

The end date/time representation (one of the values accepted by toDateTime)
string $timezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
  • 'user' (default) for the user's timezone
  • 'app' for the app's timezone
  • Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )

Return Value

int|null

Returns the difference in days (less than zero if $dateFrom if greater than $dateTo). Returns null if one of both the dates can't be parsed

Exceptions

BadArgumentType

at line 565
string formatDate(mixed $value = 'now', string $format = 'short', string $toTimezone = 'user')

Render the date part of a date/time as a localized string.

Parameters

mixed $value

$The date/time representation (one of the values accepted by toDateTime)
string $format

The format name; it can be 'full' (eg 'EEEE, MMMM d, y' - 'Wednesday, August 20, 2014'), 'long' (eg 'MMMM d, y' - 'August 20, 2014'), 'medium' (eg 'MMM d, y' - 'August 20, 2014') or 'short' (eg 'M/d/yy' - '8/20/14'), or a skeleton pattern prefixed by '~', e.g. '~yMd'. You can also append a caret ('^') or an asterisk ('') to $width. If so, special day names may be used (like 'Today', 'Yesterday', 'Tomorrow' with '^' and 'today', 'yesterday', 'tomorrow' width '') instead of the date.
string $toTimezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception

at line 597
string formatTime(mixed $value = 'now', bool $withSeconds = false, string $toTimezone = 'user')

Render the time part of a date/time as a localized string.

Parameters

mixed $value

The date/time representation (one of the values accepted by toDateTime)
bool $withSeconds

Set to true to include seconds (eg '11:59:59 PM'), false (default) otherwise (eg '11:59 PM');
string $toTimezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception
BadArgumentType

at line 623
string formatDateTime(mixed $value = 'now', bool $longDate = false, bool $withSeconds = false, string $toTimezone = 'user')

Render both the date and time parts of a date/time as a localized string.

Parameters

mixed $value

The date/time representation (one of the values accepted by toDateTime)
bool $longDate

Set to true for the long date format (eg 'December 31, 2000 at ...'), false (default) for the short format (eg '12/31/2000 at ...')
bool $withSeconds

Set to true to include seconds (eg '... at 11:59:59 PM'), false (default) otherwise (eg '... at 11:59 PM');
string $toTimezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception
BadArgumentType

at line 662
string formatPrettyDate(mixed $value, bool $longDate = false, string $toTimezone = 'user')

Render the date part of a date/time as a localized string. If the day is yesterday we'll print 'Yesterday' (the same for today, tomorrow).

Parameters

mixed $value

The date/time representation (one of the values accepted by toDateTime)
bool $longDate

Set to true for the long date format (eg 'December 31, 2000'), false (default) for the short format (eg '12/31/2000')
string $toTimezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception
BadArgumentType

at line 699
string formatPrettyDateTime(mixed $value, bool $longDate = false, bool $withSeconds = false, string $timezone = 'user')

Render both the date and time parts of a date/time as a localized string. If the day is yesterday we'll print 'Yesterday' (the same for today, tomorrow).

Parameters

mixed $value

The date/time representation (one of the values accepted by toDateTime)
bool $longDate

Set to true for the long date format (eg 'December 31, 2000 at ...'), false (default) for the short format (eg '12/31/2000 at ...')
bool $withSeconds

Set to true to include seconds (eg '... at 11:59:59 PM'), false (default) otherwise (eg '... at 11:59 PM');
string $timezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception
BadArgumentType

at line 745
string formatCustom(string $format, mixed $value = 'now', string $toTimezone = 'user', string $fromTimezone = 'system')

Render a date/time as a localized string, by specifying a custom format.

Parameters

string $format

The custom format (see http://www.php.net/manual/en/function.date.php for applicable formats)
mixed $value

The date/time representation (one of the values accepted by toDateTime)
string $toTimezone

The timezone to set. Special values are:

  • 'system' for the current system timezone
    • <li>'user' (default) for the user's timezone</li>
<li>'app' for the app's timezone</li>
<li>Other values: one of the PHP supported time zones (see http://us1.php.net/manual/en/timezones.php )</li>
string $fromTimezone

The original timezone of $value (useful only if $value is a string like '2000-12-31 23:59'); it accepts the same values as $toTimezone

Return Value

string

Returns an empty string if $value couldn't be parsed, the localized string otherwise

Exceptions

Exception
BadArgumentType

at line 761
string getJQueryUIDatePickerFormat(string $relatedPHPFormat = '')

Returns the format string for the jQueryUI DatePicker widget

Parameters

string $relatedPHPFormat

= '' Related PHP date format that will be used to parse the format handled by the DatePicker. If not specified we'll use the same format used by formatDate(..., false)

Return Value

string

Exceptions

Exception

at line 819
int getTimeFormat()

Returns the time format (12 or 24).

Return Value

int

Exceptions

Exception

at line 829
string getPHPDatePattern()

No description

Return Value

string

Exceptions

Exception

at line 847
string getPHPTimePattern()

Get the PHP date format string for times.

Return Value

string

Exceptions

Exception

at line 865
string getPHPDateTimePattern()

Get the PHP date format string for dates/times.

Return Value

string

Exceptions

Exception

at line 879
getLocalDateTime($systemDateTime = 'now', $mask = null) deprecated

deprecated

No description

Parameters

$systemDateTime
$mask

at line 914
getSystemDateTime($userDateTime = 'now', $mask = null) deprecated

deprecated

No description

Parameters

$userDateTime
$mask

at line 968
dateTimeFormatLocal($datetime, $mask) deprecated

deprecated

No description

Parameters

$datetime
$mask