aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Datetime/DateFormatterInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Datetime;
   4
   5 /**
   6  * Provides an interface defining a date formatter.
   7  */
   8 interface DateFormatterInterface {
   9
  10   /**
  11    * Formats a date, using a date type or a custom date format string.
  12    *
  13    * @param int $timestamp
  14    *   A UNIX timestamp to format.
  15    * @param string $type
  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
  31    *   display the page.
  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.
  35    *
  36    * @return string
  37    *   A translated date string in the requested format. Since the format may
  38    *   contain user input, this value should be escaped when output.
  39    */
  40   public function format($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL);
  41
  42   /**
  43    * Formats a time interval with the requested granularity.
  44    *
  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.
  50    *
  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
  55    *   default).
  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.
  60    *
  61    * @return string
  62    *   A translated string representation of the interval.
  63    *
  64    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
  65    */
  66   public function formatInterval($interval, $granularity = 2, $langcode = NULL);
  67
  68   /**
  69    * Provides values for all date formatting characters for a given timestamp.
  70    *
  71    * @param string|null $langcode
  72    *   (optional) Language code of the date format, if different from the site
  73    *   default language.
  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
  78    *   timezone.
  79    *
  80    * @return array
  81    *   An array of formatted date values, indexed by the date format character.
  82    *
  83    * @see date()
  84    */
  85   public function getSampleDateFormats($langcode = NULL, $timestamp = NULL, $timezone = NULL);
  86
  87   /**
  88    * Formats the time difference from the current request time to a timestamp.
  89    *
  90    * @param $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
  94    *   keys can be used:
  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
  99    *     page being used.
 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
 106    *     object.
 107    *
 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.
 111    *
 112    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
 113    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
 114    */
 115   public function formatTimeDiffUntil($timestamp, $options = []);
 116
 117   /**
 118    * Formats the time difference from a timestamp to the current request time.
 119    *
 120    * @param $timestamp
 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
 124    *   keys can be used:
 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
 129    *     page being used.
 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
 136    *     object.
 137    *
 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.
 141    *
 142    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatDiff()
 143    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
 144    */
 145   public function formatTimeDiffSince($timestamp, $options = []);
 146
 147   /**
 148    * Formats a time interval between two timestamps.
 149    *
 150    * @param int $from
 151    *   A UNIX timestamp, defining the from date and time.
 152    * @param int $to
 153    *   A UNIX timestamp, defining the to date and time.
 154    * @param array $options
 155    *   (optional) An associative array with additional options. The following
 156    *   keys can be used:
 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
 161    *     page being used.
 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
 167    *     object.
 168    *
 169    * @return string|\Drupal\Core\Datetime\FormattedDateDiff
 170    *   A translated string representation of the interval. This interval is
 171    *   always positive.
 172    *
 173    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatInterval()
 174    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffSince()
 175    * @see \Drupal\Core\Datetime\DateFormatterInterface::formatTimeDiffUntil()
 176    */
 177   public function formatDiff($from, $to, $options = []);
 178
 179 }