function format_date

You are here

7 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL)
4.6 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL)
4.7 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL)
5 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL)
6 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL)
8 common.inc format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL)

Format a date with the given configured format or a custom format string.

Drupal allows administrators to select formatting strings for 'small', 'medium' and 'large' date formats. This function can handle these formats, as well as any custom format.

Parameters

$timestamp: The exact date to format, as a UNIX timestamp.

$type: The format to use. Can be "small", "medium" or "large" for the preconfigured date formats. If "custom" is specified, then $format is required as well.

$format: A PHP date format string as required by date(). A backslash should be used before a character to avoid interpreting the character as part of a date format.

$timezone: Time zone offset in seconds; if omitted, the user's time zone is used.

$langcode: Optional language code to translate to a language other than what is used to display the page.

Return value

A translated date string in the requested format.

Related topics

40 calls to format_date()
blogapi_blogger_edit_post in modules/blogapi/blogapi.module
Blogging API callback. Modifies the specified blog node.
blogapi_blogger_new_post in modules/blogapi/blogapi.module
Blogging API callback. Inserts a new blog post as a node.
chameleon_comment in themes/chameleon/chameleon.theme
chameleon_node in themes/chameleon/chameleon.theme
comment_admin_overview in modules/comment/comment.admin.inc
Form builder; Builds the comment overview form for the admin.

... See full list

File

includes/common.inc, line 1354
Common functions that many Drupal modules will need to reference.

Code

function format_date($timestamp, $type = 'medium', $format = '', $timezone = NULL, $langcode = NULL) {
  if (!isset($timezone)) {
    global $user;
    if (variable_get('configurable_timezones', 1) && $user->uid && strlen($user->timezone)) {
      $timezone = $user->timezone;
    }
    else {
      $timezone = variable_get('date_default_timezone', 0);
    }
  }

  $timestamp += $timezone;

  switch ($type) {
    case 'small':
      $format = variable_get('date_format_short', 'm/d/Y - H:i');
      break;
    case 'large':
      $format = variable_get('date_format_long', 'l, F j, Y - H:i');
      break;
    case 'custom':
      // No change to format.
      break;
    case 'medium':
    default:
      $format = variable_get('date_format_medium', 'D, m/d/Y - H:i');
  }

  $max = strlen($format);
  $date = '';
  for ($i = 0; $i < $max; $i++) {
    $c = $format[$i];
    if (strpos('AaDlM', $c) !== FALSE) {
      $date .= t(gmdate($c, $timestamp), array(), $langcode);
    }
    else if ($c == 'F') {
      // Special treatment for long month names: May is both an abbreviation
      // and a full month name in English, but other languages have
      // different abbreviations.
      $date .= trim(t('!long-month-name ' . gmdate($c, $timestamp), array('!long-month-name' => ''), $langcode));
    }
    else if (strpos('BdgGhHiIjLmnsStTUwWYyz', $c) !== FALSE) {
      $date .= gmdate($c, $timestamp);
    }
    else if ($c == 'r') {
      $date .= format_date($timestamp - $timezone, 'custom', 'D, d M Y H:i:s O', $timezone, $langcode);
    }
    else if ($c == 'O') {
      $date .= sprintf('%s%02d%02d', ($timezone < 0 ? '-' : '+'), abs($timezone / 3600), abs($timezone % 3600) / 60);
    }
    else if ($c == 'Z') {
      $date .= $timezone;
    }
    else if ($c == '\\') {
      $date .= $format[++$i];
    }
    else {
      $date .= $c;
    }
  }

  return $date;
}

Comments

I used this function to convert a UNIX time stamp to a string in the format of YYYY-MM-DD:

$dateSQL = format_date($dateUnix, 'custom', 'Y-m-d');

This worked however if the user's timezone was different from the server's then it changed the actual date.
In my case the user's timezone was -05:00GMT and the server was -04:00GMT which resulted in the date 2010-03-31 changing to 2010-04-01.

The solution was to include the $timezone argument however since I did not want to change the timezone I passed an argument of 0 (zero).

$dateSQL = format_date($dateUnix, 'custom', 'Y-m-d', 0);

I also used the following code in another case:

$datePretty = format_date($dateUnix, 'medium', '', 0);

Note that I needed to pass an empty string ('') for the third argument (or I could have used null). The value of my second argument did not require the third argument ($format) to be set however without a third argument I could not pass the fourth ($format) and it is harmless to pass a value for $format as it will simply be ignored.

I would suggest to change it to:

else if ($c == 'r') {
      $date .= format_date($timestamp - $timezone, 'custom', 'D, d M Y H:i:s O', $timezone, "en");
    }

RFC 2822 (http://www.faqs.org/rfcs/rfc2822.html) Section 3.3 doesn't allow the date-time format to be localized, so this creates problems on non-English Drupal sites when creating, for instance, RSS feeds.

The format_date() API function documentation specifies that it supports the PHP date() function specifiers, but it does not actually support the "c", "e" and "P" specifiers.

Issue: http://drupal.org/node/494434

further to the last comment, format_date($stamp, 'custom', 'N'); returns 'N', not a day string as you might expect from the API docs.

"o" in the format string also only produces an "o" instead of the ISO-8601 year number, see http://www.php.net/manual/en/function.date.php . Maybe this has to do with the fact that Drupal 6 requires only PHP 4.4.0 and "o" for date() was introduced in PHP 5.1.0.