function format_date

Formats a date, using a date type or a custom date format string.

Parameters

$timestamp: A UNIX timestamp to format.

$date_format_name: (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 machine name of an administrator-defined date format.
• 'custom', to use $format.

Defaults to 'medium'.

$pattern: (optional) If $date_format_name 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.

$timezone: (optional) Time zone identifier, as described at http://php.net/manual/timezones.php Defaults to the time zone used to display the page.

$langcode: (optional) Language code to translate to. Defaults to the language used to display the page.

Return value

A translated date string in the requested format.:

Related topics

File

core/includes/common.inc, line 2468

Common functions that many Backdrop modules will need to reference.

Code

function format_date($timestamp, $date_format_name = 'medium', $pattern = '', $timezone = NULL, $langcode = NULL) {
  // Use the advanced backdrop_static() pattern, since this is called very often.
  static $backdrop_static_fast;
  if (!isset($backdrop_static_fast)) {
    $backdrop_static_fast['timezones'] = &backdrop_static(__FUNCTION__);
  }
  $timezones = &$backdrop_static_fast['timezones'];

  if (!isset($timezone)) {
    $timezone = date_default_timezone_get();
  }
  // Store DateTimeZone objects in an array rather than repeatedly
  // constructing identical objects over the life of a request.
  if (!isset($timezones[$timezone])) {
    $timezones[$timezone] = timezone_open($timezone);
  }

  // Use the interface langcode if none is set.
  global $language;
  if (empty($langcode)) {
    $langcode = isset($language->langcode) ? $language->langcode : LANGUAGE_SYSTEM;
  }

  // Create a DateTime object from the timestamp.
  $date_time = date_create('@' . $timestamp);
  // Set the time zone for the DateTime object.
  date_timezone_set($date_time, $timezones[$timezone]);

  // If we have a non-custom date format use the provided date format pattern.
  if ($date_format_name != 'custom') {
    $date_format = system_date_format_load($date_format_name);
    if (!empty($date_format)) {
      $pattern = isset($date_format['locales'][$langcode]) ? $date_format['locales'][$langcode] : $date_format['pattern'];
    }
  }

  // Fall back to medium if a format was not found.
  if (empty($pattern)) {
    $date_format = system_date_format_load('medium');
    $pattern = $date_format['pattern'];
  }

  // Encode markers that should be translated. 'A' becomes '\xEF\AA\xFF'.
  // xEF and xFF are invalid UTF-8 sequences, and we assume they are not in the
  // input string.
  // Paired backslashes are isolated to prevent errors in read-ahead evaluation.
  // The read-ahead expression ensures that A matches, but not \A.
  $pattern = preg_replace(array('/\\\\\\\\/', '/(?<!\\\\)([AaeDlMTF])/'), array("\xEF\\\\\\\\\xFF", "\xEF\\\\\$1\$1\xFF"), $pattern);

  // Call date_format().
  $formatted_date_time = date_format($date_time, $pattern);

  // Pass the langcode to _format_date_callback().
  _format_date_callback(NULL, $langcode);

  // Translate the marked sequences.
  return preg_replace_callback('/\xEF([AaeDlMTF]?)(.*?)\xFF/', '_format_date_callback', $formatted_date_time);
}