3 namespace Drupal\Core\Datetime;
6 * Provides an interface defining a date formatter.
8 interface DateFormatterInterface {
11 * Formats a date, using a date type or a custom date format string.
13 * @param int $timestamp
14 * A UNIX timestamp to format.
16 * (optional) The format to use, one of:
17 * - One of the built-in formats: 'short', 'medium',
18 * 'long', 'html_datetime', 'html_date', 'html_time',
19 * 'html_yearless_date', 'html_week', 'html_month', 'html_year'.
20 * - The name of a date type defined by a date format config entity.
21 * - The machine name of an administrator-defined date format.
22 * - 'custom', to use $format.
23 * Defaults to 'medium'.
24 * @param string $format
25 * (optional) If $type is 'custom', a PHP date format string suitable for
26 * input to date(). Use a backslash to escape ordinary text, so it does not
27 * get interpreted as date format characters.
28 * @param string|null $timezone
29 * (optional) Time zone identifier, as described at
30 * http://php.net/manual/timezones.php Defaults to the time zone used to
32 * @param string|null $langcode
33 * (optional) Language code to translate to. NULL (default) means to use
34 * the user interface language for the page.
37 * A translated date string in the requested format. Since the format may
38 * contain user input, this value should be escaped when output.
40 public function format($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL);
43 * Formats a time interval with the requested granularity.
45 * Note that for intervals over 30 days, the output is approximate: a "month"
46 * is always exactly 30 days, and a "year" is always 365 days. It is not
47 * possible to make a more exact representation, given that there is only one
48 * input in seconds. If you are formatting an interval between two specific
49 * timestamps, use \Drupal\Core\Datetime\DateFormatter::formatDiff() instead.
51 * @param int $interval
52 * The length of the interval in seconds.
53 * @param int $granularity
54 * (optional) How many different units to display in the string (2 by
56 * @param string|null $langcode
57 * (optional) langcode: The language code for the language used to format
58 * the date. Defaults to NULL, which results in the user interface language
59 * for the page being used.
62 * A translated string representation of the interval.
64 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
66 public function formatInterval($interval, $granularity = 2, $langcode = NULL);
69 * Provides values for all date formatting characters for a given timestamp.
71 * @param string|null $langcode
72 * (optional) Language code of the date format, if different from the site
74 * @param int|null $timestamp
75 * (optional) The Unix timestamp to format, defaults to current time.
76 * @param string|null $timezone
77 * (optional) The timezone to use, if different from the site's default
81 * An array of formatted date values, indexed by the date format character.
85 public function getSampleDateFormats($langcode = NULL, $timestamp = NULL, $timezone = NULL);
88 * Formats the time difference from the current request time to a timestamp.
91 * A UNIX timestamp to compare against the current request time.
92 * @param array $options
93 * (optional) An associative array with additional options. The following
95 * - granularity: An integer value that signals how many different units to
96 * display in the string. Defaults to 2.
97 * - langcode: The language code for the language used to format the date.
98 * Defaults to NULL, which results in the user interface language for the
100 * - strict: A Boolean value indicating whether or not the timestamp can be
101 * before the current request time. If TRUE (default) and $timestamp is
102 * before the current request time, the result string will be "0 seconds".
103 * If FALSE and $timestamp is before the current request time, the result
104 * string will be the formatted time difference.
105 * - return_as_object: A Boolean value whether to return a FormattedDateDiff
108 * @return string|\Drupal\Core\Datetime\FormattedDateDiff
109 * A translated string representation of the difference between the given
110 * timestamp and the current request time. This interval is always positive.
112 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
113 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
115 public function formatTimeDiffUntil($timestamp, $options = []);
118 * Formats the time difference from a timestamp to the current request time.
121 * A UNIX timestamp to compare against the current request time.
122 * @param array $options
123 * (optional) An associative array with additional options. The following
125 * - granularity: An integer value that signals how many different units to
126 * display in the string. Defaults to 2.
127 * - langcode: The language code for the language used to format the date.
128 * Defaults to NULL, which results in the user interface language for the
130 * - strict: A Boolean value indicating whether or not the timestamp can be
131 * after the current request time. If TRUE (default) and $timestamp is
132 * after the current request time, the result string will be "0 seconds".
133 * If FALSE and $timestamp is after the current request time, the result
134 * string will be the formatted time difference.
135 * - return_as_object: A Boolean value whether to return a FormattedDateDiff
138 * @return string|\Drupal\Core\Datetime\FormattedDateDiff
139 * A translated string representation of the difference between the given
140 * timestamp and the current request time. This interval is always positive.
142 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
143 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
145 public function formatTimeDiffSince($timestamp, $options = []);
148 * Formats a time interval between two timestamps.
151 * A UNIX timestamp, defining the from date and time.
153 * A UNIX timestamp, defining the to date and time.
154 * @param array $options
155 * (optional) An associative array with additional options. The following
157 * - granularity: An integer value that signals how many different units to
158 * display in the string. Defaults to 2.
159 * - langcode: The language code for the language used to format the date.
160 * Defaults to NULL, which results in the user interface language for the
162 * - strict: A Boolean value indicating whether or not the $from timestamp
163 * can be after the $to timestamp. If TRUE (default) and $from is after
164 * $to, the result string will be "0 seconds". If FALSE and $from is
165 * after $to, the result string will be the formatted time difference.
166 * - return_as_object: A Boolean value whether to return a FormattedDateDiff
169 * @return string|\Drupal\Core\Datetime\FormattedDateDiff
170 * A translated string representation of the interval. This interval is
173 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatInterval()
174 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
175 * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
177 public function formatDiff($from, $to, $options = []);