DateFormatterInterface.php

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

}