1. interface
  2. Drupal
  3. \
  4. Core
  5. \
  6. Datetime
  7. \
  8. DateFormatterInterface

DateFormatterInterface

interface DateFormatterInterface (View source)

Provides an interface defining a date formatter.

Methods

string
format(int $timestamp, string $type = 'medium', string $format = '', string|null $timezone = NULL, string|null $langcode = NULL)

Formats a date, using a date type or a custom date format string.

string
formatInterval(int $interval, int $granularity = 2, string|null $langcode = NULL)

Formats a time interval with the requested granularity.

array
getSampleDateFormats(string|null $langcode = NULL, int|null $timestamp = NULL, string|null $timezone = NULL)

Provides values for all date formatting characters for a given timestamp.

string|FormattedDateDiff
formatTimeDiffUntil($timestamp, array $options = [])

Formats the time difference from the current request time to a timestamp.

string|FormattedDateDiff
formatTimeDiffSince($timestamp, array $options = [])

Formats the time difference from a timestamp to the current request time.

string|FormattedDateDiff
formatDiff(int $from, int $to, array $options = [])

Formats a time interval between two timestamps.

Details

at line 40
string format(int $timestamp, string $type = 'medium', string $format = '', string|null $timezone = NULL, string|null $langcode = NULL)

Formats a date, using a date type or a custom date format string.

Parameters

int $timestamp

A UNIX timestamp to format.
string $type

(optional) The format to use, one of:

  • One of the built-in formats: 'short', 'medium', 'long', 'html_datetime', 'html_date', 'html_time', 'html_yearless_date', 'html_week', 'html_month', 'html_year'.
  • The name of a date type defined by a date format config entity.
  • The machine name of an administrator-defined date format.
  • 'custom', to use $format. Defaults to 'medium'.
string $format

(optional) If $type is 'custom', a PHP date format string suitable for input to date(). Use a backslash to escape ordinary text, so it does not get interpreted as date format characters.
string|null $timezone

(optional) Time zone identifier, as described at http://php.net/manual/timezones.php Defaults to the time zone used to display the page.
string|null $langcode

(optional) Language code to translate to. NULL (default) means to use the user interface language for the page.

Return Value

string

A translated date string in the requested format. Since the format may contain user input, this value should be escaped when output.

at line 66
string formatInterval(int $interval, int $granularity = 2, string|null $langcode = NULL)

Formats a time interval with the requested granularity.

Note that for intervals over 30 days, the output is approximate: a "month" is always exactly 30 days, and a "year" is always 365 days. It is not possible to make a more exact representation, given that there is only one input in seconds. If you are formatting an interval between two specific timestamps, use \Drupal\Core\Datetime\DateFormatter::formatDiff() instead.

Parameters

int $interval

The length of the interval in seconds.
int $granularity

(optional) How many different units to display in the string (2 by default).
string|null $langcode

(optional) langcode: The language code for the language used to format the date. Defaults to NULL, which results in the user interface language for the page being used.

Return Value

string

A translated string representation of the interval.

See also

DateFormatterInterface::formatDiff

at line 85
array getSampleDateFormats(string|null $langcode = NULL, int|null $timestamp = NULL, string|null $timezone = NULL)

Provides values for all date formatting characters for a given timestamp.

Parameters

string|null $langcode

(optional) Language code of the date format, if different from the site default language.
int|null $timestamp

(optional) The Unix timestamp to format, defaults to current time.
string|null $timezone

(optional) The timezone to use, if different from the site's default timezone.

Return Value

array

An array of formatted date values, indexed by the date format character.

See also

date()

at line 115
string|FormattedDateDiff formatTimeDiffUntil($timestamp, array $options = [])

Formats the time difference from the current request time to a timestamp.

Parameters

$timestamp

A UNIX timestamp to compare against the current request time.
array $options

(optional) An associative array with additional options. The following keys can be used:

  • granularity: An integer value that signals how many different units to display in the string. Defaults to 2.
  • langcode: The language code for the language used to format the date. Defaults to NULL, which results in the user interface language for the page being used.
  • strict: A Boolean value indicating whether or not the timestamp can be before the current request time. If TRUE (default) and $timestamp is before the current request time, the result string will be "0 seconds". If FALSE and $timestamp is before the current request time, the result string will be the formatted time difference.
  • return_as_object: A Boolean value whether to return a FormattedDateDiff object.

Return Value

string|FormattedDateDiff

A translated string representation of the difference between the given timestamp and the current request time. This interval is always positive.

See also

DateFormatterInterface::formatDiff
DateFormatterInterface::formatTimeDiffSince

at line 145
string|FormattedDateDiff formatTimeDiffSince($timestamp, array $options = [])

Formats the time difference from a timestamp to the current request time.

Parameters

$timestamp

A UNIX timestamp to compare against the current request time.
array $options

(optional) An associative array with additional options. The following keys can be used:

  • granularity: An integer value that signals how many different units to display in the string. Defaults to 2.
  • langcode: The language code for the language used to format the date. Defaults to NULL, which results in the user interface language for the page being used.
  • strict: A Boolean value indicating whether or not the timestamp can be after the current request time. If TRUE (default) and $timestamp is after the current request time, the result string will be "0 seconds". If FALSE and $timestamp is after the current request time, the result string will be the formatted time difference.
  • return_as_object: A Boolean value whether to return a FormattedDateDiff object.

Return Value

string|FormattedDateDiff

A translated string representation of the difference between the given timestamp and the current request time. This interval is always positive.

See also

DateFormatterInterface::formatDiff
DateFormatterInterface::formatTimeDiffUntil

at line 177
string|FormattedDateDiff formatDiff(int $from, int $to, array $options = [])

Formats a time interval between two timestamps.

Parameters

int $from

A UNIX timestamp, defining the from date and time.
int $to

A UNIX timestamp, defining the to date and time.
array $options

(optional) An associative array with additional options. The following keys can be used:

  • granularity: An integer value that signals how many different units to display in the string. Defaults to 2.
  • langcode: The language code for the language used to format the date. Defaults to NULL, which results in the user interface language for the page being used.
  • strict: A Boolean value indicating whether or not the $from timestamp can be after the $to timestamp. If TRUE (default) and $from is after $to, the result string will be "0 seconds". If FALSE and $from is after $to, the result string will be the formatted time difference.
  • return_as_object: A Boolean value whether to return a FormattedDateDiff object.

Return Value

string|FormattedDateDiff

A translated string representation of the interval. This interval is always positive.

See also

DateFormatterInterface::formatInterval
DateFormatterInterface::formatTimeDiffSince
DateFormatterInterface::formatTimeDiffUntil