7.x system.api.php hook_date_formats()

Define additional date formats.

This hook is used to define the PHP date format strings that can be assigned to date types in the administrative interface. A module can provide date format strings for the core-provided date types ('long', 'medium', and 'short'), or for date types defined in hook_date_format_types() by itself or another module.

Since date formats can be locale-specific, you can specify the locales that each date format string applies to. There may be more than one locale for a format. There may also be more than one format for the same locale. For example d/m/Y and Y/m/d work equally well in some locales. You may wish to define some additional date formats that aren't specific to any one locale, for example, "Y m". For these cases, the 'locales' component of the return value should be omitted.

Providing a date format here does not normally assign the format to be used with the associated date type -- a user has to choose a format for each date type in the administrative interface. There is one exception: locale initialization chooses a locale-specific format for the three core-provided types (see locale_get_localized_date_format() for details). If your module needs to ensure that a date type it defines has a format associated with it, call

variable_set('date_format_' . $type, $format);

where $type is the machine-readable name defined in hook_date_format_types(), and $format is a PHP date format string.

Return value

A list of date formats to offer as choices in the administrative interface. Each date format is a keyed array consisting of three elements:

  • 'type': The date type name that this format can be used with, as declared in an implementation of hook_date_format_types().
  • 'format': A PHP date format string to use when formatting dates. It can contain any of the formatting options described at http://php.net/manual/function.date.php
  • 'locales': (optional) An array of 2 and 5 character locale codes, defining which locales this format applies to (for example, 'en', 'en-us', etc.). If your date format is not language-specific, leave this array empty.

See also


Related topics

3 functions implement hook_date_formats()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

system_date_formats in modules/system/system.module
Implements hook_date_formats().
system_default_date_formats in includes/date.inc
Provides a default system list of date formats for system_date_formats().
system_get_date_formats in modules/system/system.module
Gets the list of defined date formats and attributes.
1 invocation of hook_date_formats()
_system_date_formats_build in modules/system/system.module
Builds and returns information about available date formats.


modules/system/system.api.php, line 4215
Hooks provided by Drupal core and the System module.


function hook_date_formats() {
  return array(
      'type' => 'mymodule_extra_long',
      'format' => 'l jS F Y H:i:s e',
      'locales' => array(
      'type' => 'mymodule_extra_long',
      'format' => 'l jS F Y h:i:sa',
      'locales' => array(
      'type' => 'short',
      'format' => 'F Y',
      'locales' => array(),


OnkelTem’s picture

I wonder why implement all these date hooks which almost do nothing except returning PHP's date formatting string which also can be entered in the admin UI as string...

To my mind, the most obvious thing which is really needed here - is the ability to specify _user_ function for date formatting, like:

      'type' => 'my_trivial_date_localization_which_nobody_implemented_still_in_2011', 
      'callback' =>  'localize_this_date',
      'locales' => array('ru'),
SKAUGHT’s picture

doitDave’s picture

Regardless of what I set "locales" to, the formats will not appear in the configuration dropdown. The actually appear at no place except when invoking hook_date_formats.

sourabhutani’s picture

I'm creating custom format like below but not able to create the format as i want.It gives me format like http://screencast.com/t/C9Ubl8h73o .I need this format "1T1M33S"

function video_schema_date_formats() {
$formats = array();
$formats[] = array(
'type' => 'video_schema_format',
'format' => 'h\Ti\Ms\S',
'locales' => array(),
foreach ($formats as $format) {
variable_set('date_format_' . $format['type'], $format['format']);
return $formats;