123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179 |
- <?php
- namespace Drupal\Core\Datetime;
- /**
- * Provides an interface defining a date formatter.
- */
- interface DateFormatterInterface {
- /**
- * Formats a date, using a date type or a custom date format string.
- *
- * @param int $timestamp
- * A UNIX timestamp to format.
- * @param 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'.
- * @param 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.
- * @param 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.
- * @param string|null $langcode
- * (optional) Language code to translate to. NULL (default) means to use
- * the user interface language for the page.
- *
- * @return string
- * A translated date string in the requested format. Since the format may
- * contain user input, this value should be escaped when output.
- */
- public function format($timestamp, $type = 'medium', $format = '', $timezone = 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.
- *
- * @param int $interval
- * The length of the interval in seconds.
- * @param int $granularity
- * (optional) How many different units to display in the string (2 by
- * default).
- * @param 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 string
- * A translated string representation of the interval.
- *
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
- */
- public function formatInterval($interval, $granularity = 2, $langcode = NULL);
- /**
- * Provides values for all date formatting characters for a given timestamp.
- *
- * @param string|null $langcode
- * (optional) Language code of the date format, if different from the site
- * default language.
- * @param int|null $timestamp
- * (optional) The Unix timestamp to format, defaults to current time.
- * @param string|null $timezone
- * (optional) The timezone to use, if different from the site's default
- * timezone.
- *
- * @return array
- * An array of formatted date values, indexed by the date format character.
- *
- * @see date()
- */
- public function getSampleDateFormats($langcode = NULL, $timestamp = NULL, $timezone = NULL);
- /**
- * Formats the time difference from the current request time to a timestamp.
- *
- * @param $timestamp
- * A UNIX timestamp to compare against the current request time.
- * @param 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 string|\Drupal\Core\Datetime\FormattedDateDiff
- * A translated string representation of the difference between the given
- * timestamp and the current request time. This interval is always positive.
- *
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
- */
- public function formatTimeDiffUntil($timestamp, $options = []);
- /**
- * Formats the time difference from a timestamp to the current request time.
- *
- * @param $timestamp
- * A UNIX timestamp to compare against the current request time.
- * @param 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 string|\Drupal\Core\Datetime\FormattedDateDiff
- * A translated string representation of the difference between the given
- * timestamp and the current request time. This interval is always positive.
- *
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
- */
- public function formatTimeDiffSince($timestamp, $options = []);
- /**
- * Formats a time interval between two timestamps.
- *
- * @param int $from
- * A UNIX timestamp, defining the from date and time.
- * @param int $to
- * A UNIX timestamp, defining the to date and time.
- * @param 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 string|\Drupal\Core\Datetime\FormattedDateDiff
- * A translated string representation of the interval. This interval is
- * always positive.
- *
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatInterval()
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
- * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
- */
- public function formatDiff($from, $to, $options = []);
- }
|