interface DateFormatterInterface

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 = []);

}