- Patch #854396 by tstoeckler, jhodgdon: improve documentation for date-related functions and hooks in system.module.

2 files changed, 185 insertions, 121 deletions

diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index b9c8209cd..3d73c0647 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -3681,7 +3681,7 @@ function hook_archiver_info_alter(&$info) {
 }
 
 /**
- * Defines additional date types.
+ * Define additional date types.
  *
  * Next to the 'long', 'medium' and 'short' date types defined in core, any
  * module can define additional types that can be used when displaying dates. A
@@ -3693,7 +3693,8 @@ function hook_archiver_info_alter(&$info) {
  * can consist of letters, numbers and underscores.
  *
  * @return
- *   A list of date types in 'key' => 'label' format.
+ *   An array of date types where the keys are the machine-readable names and
+ *   the values are the human-readable labels.
  *
  * @see hook_date_formats()
  * @see format_date()
@@ -3707,72 +3708,65 @@ function hook_date_format_types() {
 }
 
 /**
- * Modify existing date format types.
+ * Modify existing date types.
  *
- * Allows other modules to modify existing date types like 'long'. Called
- * by _system_date_format_types_build(). For instance, A module may use this
- * hook to apply settings across all date format types, such as locking all
- * date format types so they appear to be provided by the system.
+ * Allows other modules to modify existing date types like 'long'. Called by
+ * _system_date_format_types_build(). For instance, A module may use this hook
+ * to apply settings across all date types, such as locking all date types so
+ * they appear to be provided by the system.
  *
  * @param $types
- *   An associative array of date format types containing:
- *   - types:  An array of date format types including configuration settings
- *     for each type:
- *     - is_new: Set to FALSE to override previous settings.
- *     - module: The name of the module that created the date format type.
- *     - type: The date type name.
- *     - title: The title of the date type.
- *     - locked: Specifies that the date type is system-provided.
+ *   A list of date types. Each date type is keyed by name and the values are
+ *   associative arrays containing:
+ *   - is_new: Set to FALSE to override previous settings.
+ *   - module: The name of the module that created the date format type.
+ *   - type: The date type name.
+ *   - title: The title of the date type.
+ *   - locked: Specifies that the date type is system-provided.
  */
 function hook_date_format_types_alter(&$types) {
-  foreach ($types as $type_name => $type) {
-    $types[$type_name]['locked'] = 1;
+  foreach ($types as $name => $type) {
+    $types[$name]['locked'] = 1;
   }
 }
 
 /**
- * Defines additional date formats.
- *
- * Next to the 'long', 'medium' and 'short' date types defined in core, any
- * module can define additional types that can be used when displaying dates. A
- * date type is a key which can be passed to format_date() to return a date in
- * the configured displayed format. A date format is a string defining the date
- * and time elements to use. For example, a date type could be
- * 'mymodule_extra_long', while a date format is like 'Y-m-d'.
- *
- * New date types must first be declared using hook_date_format_types(). It is
- * then possible to define one or more date formats for each.
- *
- * A module may also extend the list date formats defined for a date type
- * provided by another module.
- *
- * There may be more than one format for the same locale. For example d/m/Y and
- * Y/m/d work equally well in some locales. It may also be necessary to define
- * multiple versions of the same date format, for example, one using AM, one
- * with PM and one without the time at all.
- *
- * However at the same time 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 field should be omitted.
+ * Define additional date formats.
+ *
+ * This hook is used to define the date format strings that are used to format
+ * date types for different locales. Next to the 'long', 'medium' and 'short'
+ * date types defined in core, any module can define additional date types in
+ * hook_date_format_types(). For example, a date type could be
+ * 'mymodule_extra_long' (defined in mymodule_date_format_types()), while a date
+ * format string is like 'Y-m-d' and can be defined with this hook.
+ *
+ * A module may use this hook to provide date format strings for its own date
+ * types provided in hook_date_format_types() or add date format strings to a
+ * date type provided by another module or to the 'long', 'medium' and 'short'
+ * date types provided by core.
+ *
+ * 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 should be omitted.
  *
  * @return
- *   A list of date formats. Each date format is a keyed array
- *   consisting of three elements:
- *   - 'type': the date type is a key used to identify which date format to
- *     display. It consists of letters, numbers and underscores, e.g. 'long',
- *     'short', 'mymodule_extra_long'. It must first be declared in
- *     hook_date_format_types() unless extending a type provided by another
- *     module.
- *   - 'format': a string defining the date and time elements to use. It
+ *   A list of date formats. Each date format is a keyed array consisting of
+ *   three elements:
+ *   - 'type': The date type name, 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/en/function.date.php
- *   - 'locales': (optional) an array of 2 and 5 character language codes, for
+ *   - 'locales': (optional) An array of 2 and 5 character locale codes; for
  *     example, 'en', 'en-us'. The language codes are used to determine which
- *     date format to display for the user's current language. If more than one
+ *     date format to display for the user's current locale. If more than one
  *     date format is suggested for the same date type and locale, then the
- *     first one will be used unless overridden via
+ *     first one will be used unless overridden via the administrative UI at
  *     admin/config/regional/date-time/locale. If your date format is not
- *     language specific, leave this field empty.
+ *     language-specific, leave this array empty.
  *
  * @see hook_date_format_types()
  */
@@ -3797,7 +3791,7 @@ function hook_date_formats() {
 }
 
 /**
- * Alters date types and formats declared by another module.
+ * Alter date formats declared by another module.
  *
  * Called by _system_date_format_types_build() to allow modules to alter the
  * return values from implementations of hook_date_formats().
diff --git a/modules/system/system.module b/modules/system/system.module
index 46c4838c8..1d60e625f 100644
--- a/modules/system/system.module
+++ b/modules/system/system.module
@@ -3459,22 +3459,34 @@ function system_run_automated_cron() {
 }
 
 /**
- * Get the list of available date types and attributes.
+ * Gets the list of available date types and attributes.
  *
  * @param $type
- *   The date type, e.g. 'short', 'medium', 'long', 'custom'. If empty, then
- *   all attributes for that type will be returned.
+ *   (optional) The date type name.
+ *
  * @return
- *   Array of date types.
+ *   An associative array of date type information keyed by the date type name.
+ *   Each date type information array has the following elements:
+ *   - type: The machine-readable name of the date type.
+ *   - title: The human-readable name of the date type.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: The name of the module that defined this date type in its
+ *     hook_date_format_types(). An empty string if the date type was
+ *     user-defined.
+ *   - is_new: A boolean indicating whether or not this date type is as of yet
+ *     unsaved in the database.
+ *   If $type was defined, only a single associative array with the above
+ *   elements is returned.
  */
 function system_get_date_types($type = NULL) {
-  $date_format_types = &drupal_static(__FUNCTION__);
+  $types = &drupal_static(__FUNCTION__);
 
-  if (!isset($date_format_types)) {
-    $date_format_types = _system_date_format_types_build();
+  if (!isset($types)) {
+    $types = _system_date_format_types_build();
   }
 
-  return $type ? (isset($date_format_types[$type]) ? $date_format_types[$type] : FALSE) : $date_format_types;
+  return $type ? (isset($types[$type]) ? $types[$type] : FALSE) : $types;
 }
 
 /**
@@ -3490,12 +3502,6 @@ function system_date_format_types() {
 
 /**
  * Implements hook_date_formats().
- *
- * @return
- *   An array of date formats with attributes 'type' (short, medium or long),
- *   'format' (the format string) and 'locales'. The 'locales' attribute is an
- *   array of locales, which can include both 2 character language codes like
- *   'en', 'fr', but also 5 character language codes like 'en-gb' and 'en-us'.
  */
 function system_date_formats() {
   include_once DRUPAL_ROOT . '/includes/date.inc';
@@ -3503,13 +3509,29 @@ function system_date_formats() {
 }
 
 /**
- * Get the list of date formats for a particular format length.
+ * Gets the list of defined date formats and attributes.
  *
  * @param $type
- *   The date type: 'short', 'medium', 'long', 'custom'. If empty, then all
- *   available types will be returned.
+ *   (optional) The date type name.
+ *
  * @return
- *   Array of date formats.
+ *   An associative array of date formats. The top-level keys are the names of
+ *   the date types that the date formats belong to. The values are in turn
+ *   associative arrays keyed by the format string, with the following keys:
+ *   - dfid: The date format ID.
+ *   - format: The format string.
+ *   - type: The machine-readable name of the date type.
+ *   - locales: An array of language codes. This can include both 2 character
+ *     language codes like 'en and 'fr' and 5 character language codes like
+ *     'en-gb' and 'en-us'.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: The name of the module that defined this date format in its
+ *     hook_date_formats(). An empty string if the format was user-defined.
+ *   - is_new: A boolean indicating whether or not this date type is as of yet
+ *     unsaved in the database.
+ *   If $type was defined, only the date formats associated with the given date
+ *   type are returned, in a single associative array keyed by format string.
  */
 function system_get_date_formats($type = NULL) {
   $date_formats = &drupal_static(__FUNCTION__);
@@ -3522,25 +3544,30 @@ function system_get_date_formats($type = NULL) {
 }
 
 /**
- * Get the format details for a particular id.
+ * Gets the format details for a particular format ID.
  *
  * @param $dfid
- *   Identifier of a date format string.
+ *   A date format ID.
+ *
  * @return
- *   Array of date format details.
+ *   A date format object with the following properties:
+ *   - dfid: The date format ID.
+ *   - format: The date format string.
+ *   - type: The name of the date type.
+ *   - locked: Whether the date format can be changed or not.
  */
 function system_get_date_format($dfid) {
   return db_query('SELECT df.dfid, df.format, df.type, df.locked FROM {date_formats} df WHERE df.dfid = :dfid', array(':dfid' => $dfid))->fetch();
 }
 
 /**
- * Resets the database cache of date formats and saves all new formats.
+ * Resets the database cache of date formats and saves all new date formats.
  */
 function system_date_formats_rebuild() {
   drupal_static_reset('system_get_date_formats');
   $date_formats = system_get_date_formats(NULL);
 
-  foreach ($date_formats as $format_type => $formats) {
+  foreach ($date_formats as $type => $formats) {
     foreach ($formats as $format => $info) {
       system_date_format_save($info);
     }
@@ -3554,15 +3581,20 @@ function system_date_formats_rebuild() {
 }
 
 /**
- * Get the appropriate date format for a type and locale.
+ * Gets the appropriate date format string for a date type and locale.
  *
  * @param $langcode
- *   Language code for the current locale. This can be a 2 character language
- *   code like 'en', 'fr', or a longer 5 character code like 'en-gb'.
+ *   (optional) Language code for the current locale. This can be a 2 character
+ *   language code like 'en' and 'fr' or a 5 character language code like
+ *   'en-gb' and 'en-us'.
  * @param $type
- *   Date type: short, medium, long, custom.
+ *   (optional) The date type name.
+ *
  * @return
- *   The format string, or NULL if no matching format found.
+ *   If $type and $langcode are specified, returns the corresponding date format
+ *   string. If only $langcode is specified, returns an array of all date
+ *   format strings for that locale, keyed by the date type. If neither is
+ *   specified, or if no matching formats are found, returns FALSE.
  */
 function system_date_format_locale($langcode = NULL, $type = NULL) {
   $formats = &drupal_static(__FUNCTION__);
@@ -3589,10 +3621,19 @@ function system_date_format_locale($langcode = NULL, $type = NULL) {
 }
 
 /**
- * Builds and returns the list of available date types.
+ * Builds and returns information about available date types.
  *
  * @return
- *   Array of date types.
+ *   An associative array of date type information keyed by name. Each date type
+ *   information array has the following elements:
+ *   - type: The machine-readable name of the date type.
+ *   - title: The human-readable name of the date type.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: The name of the module that defined this format in its
+ *     hook_date_format_types(). An empty string if the format was user-defined.
+ *   - is_new: A boolean indicating whether or not this date type is as of yet
+ *     unsaved in the database.
  */
 function _system_date_format_types_build() {
   $types = array();
@@ -3608,7 +3649,8 @@ function _system_date_format_types_build() {
       $type['type'] = $module_type;
       $type['title'] = $type_title;
       $type['locked'] = 1;
-      $type['is_new'] = TRUE; // Will be over-ridden later if in the db.
+      // Will be over-ridden later if in the db.
+      $type['is_new'] = TRUE;
       $types[$module_type] = $type;
     }
   }
@@ -3639,10 +3681,24 @@ function _system_date_format_types_build() {
 }
 
 /**
- * Builds and returns the list of available date formats.
+ * Builds and returns information about available date formats.
  *
  * @return
- *   Array of date formats.
+ *   An associative array of date formats. The top-level keys are the names of
+ *   the date types that the date formats belong to. The values are in turn
+ *   associative arrays keyed by format with the following keys:
+ *   - dfid: The date format ID.
+ *   - format: The PHP date format string.
+ *   - type: The machine-readable name of the date type the format belongs to.
+ *   - locales: An array of language codes. This can include both 2 character
+ *     language codes like 'en and 'fr' and 5 character language codes like
+ *     'en-gb' and 'en-us'.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: The name of the module that defined this format in its
+ *     hook_date_formats(). An empty string if the format was user-defined.
+ *   - is_new: A boolean indicating whether or not this date type is as of yet
+ *     unsaved in the database.
  */
 function _system_date_formats_build() {
   $date_formats = array();
@@ -3657,7 +3713,8 @@ function _system_date_formats_build() {
   $module_formats = module_invoke_all('date_formats');
 
   foreach ($module_formats as $module_format) {
-    $module_format['locked'] = 1; // System types are locked.
+    // System types are locked.
+    $module_format['locked'] = 1;
     // If no date type is specified, assign 'custom'.
     if (!isset($module_format['type'])) {
       $module_format['type'] = 'custom';
@@ -3671,7 +3728,7 @@ function _system_date_formats_build() {
 
     // If another module already set this format, merge in the new settings.
     if (isset($date_formats[$module_format['type']][$module_format['format']])) {
-      $date_formats[$module_format['type']][$module_format['format']] = array_merge_recursive($date_formats[$module_format['type']][$module_format['format']], $format);
+      $date_formats[$module_format['type']][$module_format['format']] = array_merge_recursive($date_formats[$module_format['type']][$module_format['format']], $module_format);
     }
     else {
       // This setting will be overridden later if it already exists in the db.
@@ -3711,67 +3768,80 @@ function _system_date_formats_build() {
 }
 
 /**
- * Save a date type to the database.
+ * Saves a date type to the database.
  *
- * @param $date_format_type
- *   An array of attributes for a date type.
- */
-function system_date_format_type_save($date_format_type) {
-  $type = array();
-  $type['type'] = $date_format_type['type'];
-  $type['title'] = $date_format_type['title'];
-  $type['locked'] = $date_format_type['locked'];
+ * @param $type
+ *   A date type array containing the following keys:
+ *   - type: The machine-readable name of the date type.
+ *   - title: The human-readable name of the date type.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - is_new: A boolean indicating whether or not this date type is as of yet
+ *     unsaved in the database.
+ */
+function system_date_format_type_save($type) {
+  $info = array();
+  $info['type'] = $type['type'];
+  $info['title'] = $type['title'];
+  $info['locked'] = $type['locked'];
 
   // Update date_format table.
-  if (!empty($date_format_type['is_new'])) {
-    drupal_write_record('date_format_type', $type);
+  if (!empty($type['is_new'])) {
+    drupal_write_record('date_format_type', $info);
   }
   else {
-    drupal_write_record('date_format_type', $type, 'type');
+    drupal_write_record('date_format_type', $info, 'type');
   }
 }
 
 /**
- * Delete a date type from the database.
+ * Deletes a date type from the database.
  *
- * @param $date_format_type
- *   The date type name.
+ * @param $type
+ *   The machine-readable name of the date type.
  */
-function system_date_format_type_delete($date_format_type) {
+function system_date_format_type_delete($type) {
   db_delete('date_formats')
-    ->condition('type', $date_format_type)
+    ->condition('type', $type)
     ->execute();
   db_delete('date_format_type')
-    ->condition('type', $date_format_type)
+    ->condition('type', $type)
     ->execute();
   db_delete('date_format_locale')
-    ->condition('type', $date_format_type)
+    ->condition('type', $type)
     ->execute();
 }
 
 /**
- * Save a date format to the database.
+ * Saves a date format to the database.
  *
  * @param $date_format
- *   An array of attributes for a date format.
+ *   A date format array containing the following keys:
+ *   - type: The name of the date type this format is associated with.
+ *   - format: The PHP date format string.
+ *   - locked: A boolean indicating whether or not this format should be
+ *     configurable from the user interface.
  * @param $dfid
- *   If set, replace an existing date format with a new string using this
- *   identifier.
+ *   If set, replace the existing date format having this ID with the
+ *   information specified in $date_format.
+ *
+ * @see system_get_date_types()
+ * @see http://php.net/date
  */
 function system_date_format_save($date_format, $dfid = 0) {
-  $format = array();
-  $format['dfid'] = $dfid;
-  $format['type'] = $date_format['type'];
-  $format['format'] = $date_format['format'];
-  $format['locked'] = $date_format['locked'];
+  $info = array();
+  $info['dfid'] = $dfid;
+  $info['type'] = $date_format['type'];
+  $info['format'] = $date_format['format'];
+  $info['locked'] = $date_format['locked'];
 
   // Update date_format table.
   if (!empty($date_format['is_new'])) {
-    drupal_write_record('date_formats', $format);
+    drupal_write_record('date_formats', $info);
   }
   else {
     $keys = ($dfid ? array('dfid') : array('format', 'type'));
-    drupal_write_record('date_formats', $format, $keys);
+    drupal_write_record('date_formats', $info, $keys);
   }
 
   $languages = language_list('enabled');
@@ -3797,10 +3867,10 @@ function system_date_format_save($date_format, $dfid = 0) {
 }
 
 /**
- * Delete a date format from the database.
+ * Deletes a date format from the database.
  *
- * @param $date_format_id
- *   The date format string identifier.
+ * @param $dfid
+ *   The date format ID.
  */
 function system_date_format_delete($dfid) {
   db_delete('date_formats')