? profiles/testing
Index: modules/system/system.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/system/system.module,v
retrieving revision 1.953
diff -u -p -r1.953 system.module
--- modules/system/system.module	9 Aug 2010 16:54:50 -0000	1.953
+++ modules/system/system.module	11 Aug 2010 17:36:41 -0000
@@ -3286,22 +3286,33 @@ function system_run_automated_cron() {
 }
 
 /**
- * Get the list of available date types and attributes.
+ * Gets the list of available date types and attributes.
+ *
+ * @param $date_type
+ *   (optional) A string containing the date type name.
  *
- * @param $type
- *   The date type, e.g. 'short', 'medium', 'long', 'custom'. If empty, then
- *   all attributes for that type will be returned.
  * @return
- *   Array of date types.
+ *   An associative array of date types keyed by name. Each date type is in turn
+ *   an associative array with the following keys:
+ *   - type: A string containing the machine-readable name of the date type.
+ *   - title: A string containing the user interface name of the date type.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: A string containing the name of the module that defined it 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 does not exist
+ *     in the database yet.
+ *   If $date_type was defined, only a single associative array with the above
+ *   keys.
  */
-function system_get_date_types($type = NULL) {
-  $date_format_types = &drupal_static(__FUNCTION__);
+function system_get_date_types($date_type = NULL) {
+  $date_types = &drupal_static(__FUNCTION__);
 
-  if (!isset($date_format_types)) {
-    $date_format_types = _system_date_format_types_build();
+  if (!isset($date_types)) {
+    $date_types = _system_date_format_types_build();
   }
 
-  return $type ? (isset($date_format_types[$type]) ? $date_format_types[$type] : FALSE) : $date_format_types;
+  return $date_type ? (isset($date_types[$date_type]) ? $date_types[$date_type] : FALSE) : $date_types;
 }
 
 /**
@@ -3317,12 +3328,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';
@@ -3330,45 +3335,66 @@ function system_date_formats() {
 }
 
 /**
- * Get the list of date formats for a particular format length.
+ * Gets the list of date formats for a particular date type.
+ *
+ * @param $date_type
+ *   (optional) A string containing the date type name.
  *
- * @param $type
- *   The date type: 'short', 'medium', 'long', 'custom'. If empty, then all
- *   available types will be returned.
  * @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:
+ *   - dfif: The date format ID.
+ *   - format: A format string.
+ *   - type: A string containing 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', but also 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: A string containing the name of the module that defined it 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 does not exist
+ *     in the database yet.
+ *   If $date_type was defined, only a single associative array keyed by format.
+ *   The values are in turn associative arrays with the above keys.
  */
-function system_get_date_formats($type = NULL) {
+function system_get_date_formats($date_type = NULL) {
   $date_formats = &drupal_static(__FUNCTION__);
 
   if (!isset($date_formats)) {
     $date_formats = _system_date_formats_build();
   }
 
-  return $type ? (isset($date_formats[$type]) ? $date_formats[$type] : FALSE) : $date_formats;
+  return $date_type ? (isset($date_formats[$date_type]) ? $date_formats[$date_type] : FALSE) : $date_formats;
 }
 
 /**
- * Get the format details for a particular id.
+ * Gets the format details for a particular id.
  *
  * @param $dfid
- *   Identifier of a date format string.
+ *   A date format ID.
+ *
  * @return
- *   Array of date format details.
+ *   An associative array of date format details with the following keys:
+ *   - dfif: The date format ID.
+ *   - format: A format string.
+ *   - type: A string containing 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);
+  $date_formats_array = system_get_date_formats(NULL);
 
-  foreach ($date_formats as $format_type => $formats) {
-    foreach ($formats as $format => $info) {
+  foreach ($date_formats_array as $date_type => $date_formats) {
+    foreach ($date_formats as $format => $info) {
       system_date_format_save($info);
     }
   }
@@ -3381,35 +3407,37 @@ function system_date_formats_rebuild() {
 }
 
 /**
- * Get the appropriate date format for a type and locale.
+ * Gets the appropriate date format 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'.
- * @param $type
- *   Date type: short, medium, long, custom.
+ *   (optional) Language code for the current locale. This can be a 2 character
+ *   language code like 'en' and 'fr', but also a 5 character language code like
+ *   'en-gb' and 'en-us'.
+ * @param $date_type
+ *   (optional) A string containing the date type name.
+ *
  * @return
- *   The format string, or NULL if no matching format found.
+ *   A format string, or FALSE if no matching format found.
  */
-function system_date_format_locale($langcode = NULL, $type = NULL) {
-  $formats = &drupal_static(__FUNCTION__);
+function system_date_format_locale($langcode = NULL, $date_type = NULL) {
+  $date_formats = &drupal_static(__FUNCTION__);
 
-  if (empty($formats)) {
-    $formats = array();
+  if (empty($date_formats)) {
+    $date_formats = array();
     $result = db_query("SELECT format, type, language FROM {date_format_locale}");
     foreach ($result as $record) {
-      if (!isset($formats[$record->language])) {
-        $formats[$record->language] = array();
+      if (!isset($date_formats[$record->language])) {
+        $date_formats[$record->language] = array();
       }
-      $formats[$record->language][$record->type] = $record->format;
+      $date_formats[$record->language][$record->type] = $record->format;
     }
   }
 
-  if ($type && $langcode && !empty($formats[$langcode][$type])) {
-    return $formats[$langcode][$type];
+  if ($date_type && $langcode && !empty($date_formats[$langcode][$type])) {
+    return $date_formats[$langcode][$type];
   }
-  elseif ($langcode && !empty($formats[$langcode])) {
-    return $formats[$langcode];
+  elseif ($langcode && !empty($date_formats[$langcode])) {
+    return $date_formats[$langcode];
   }
 
   return FALSE;
@@ -3419,7 +3447,18 @@ function system_date_format_locale($lang
  * Builds and returns the list of available date types.
  *
  * @return
- *   Array of date types.
+ *   An associative array of date types keyed by name. Each date type is in turn
+ *   an associative array with the following keys:
+ *   - type: A string containing the machine-readable name of the date type.
+ *   - title: A string containing the user interface name of the date type.
+ *   - locked: A boolean indicating whether or not this date type should be
+ *     configurable from the user interface.
+ *   - module: A string containing the name of the module that defined it 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 does not exist
+ *     in the database yet.
+ *   If $date_type was defined, only a single associative array with the above
+ *   keys.
  */
 function _system_date_format_types_build() {
   $types = array();
@@ -3430,13 +3469,14 @@ function _system_date_format_types_build
   foreach ($modules as $module) {
     $module_types = module_invoke($module, 'date_format_types');
     foreach ($module_types as $module_type => $type_title) {
-      $type = array();
-      $type['module'] = $module;
-      $type['type'] = $module_type;
-      $type['title'] = $type_title;
-      $type['locked'] = 1;
-      $type['is_new'] = TRUE; // Will be over-ridden later if in the db.
-      $types[$module_type] = $type;
+      $date_type = array();
+      $date_type['module'] = $module;
+      $date_type['type'] = $module_type;
+      $date_type['title'] = $type_title;
+      $date_type['locked'] = 1;
+      // Will be over-ridden later if in the db.
+      $date_type['is_new'] = TRUE;
+      $date_types[$module_type] = $date_type;
     }
   }
 
@@ -3444,39 +3484,55 @@ function _system_date_format_types_build
   $result = db_query('SELECT dft.type, dft.title, dft.locked FROM {date_format_type} dft ORDER BY dft.title');
   foreach ($result as $record) {
     if (!in_array($record->type, $types)) {
-      $type = array();
-      $type['is_new'] = FALSE;
-      $type['module'] = '';
-      $type['type'] = $record->type;
-      $type['title'] = $record->title;
-      $type['locked'] = $record->locked;
-      $types[$record->type] = $type;
+      $date_type = array();
+      $date_type['is_new'] = FALSE;
+      $date_type['module'] = '';
+      $date_type['type'] = $record->type;
+      $date_type['title'] = $record->title;
+      $date_type['locked'] = $record->locked;
+      $date_types[$record->type] = $date_type;
     }
     else {
-      $type = array();
-      $type['is_new'] = FALSE;  // Over-riding previous setting.
-      $types[$record->type] = array_merge($types[$record->type], $type);
+      $date_type = array();
+      $date_type['is_new'] = FALSE;  // Over-riding previous setting.
+      $date_types[$record->type] = array_merge($date_types[$record->type], $date_type);
     }
   }
 
   // Allow other modules to modify these date types.
-  drupal_alter('date_format_types', $types);
+  drupal_alter('date_format_types', $date_types);
 
-  return $types;
+  return $date_types;
 }
 
 /**
  * Builds and returns the list of 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:
+ *   - dfif: The date format ID.
+ *   - format: A format string.
+ *   - type: A string containing 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', but also 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: A string containing the name of the module that defined it 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 does not exist
+ *     in the database yet.
+ *   If $date_type was defined, only a single associative array keyed by format.
+ *   The values are in turn associative arrays with the above keys.
  */
 function _system_date_formats_build() {
   $date_formats = array();
 
   // First handle hook_date_format_types().
-  $types = _system_date_format_types_build();
-  foreach ($types as $type => $info) {
+  $date_types = _system_date_format_types_build();
+  foreach ($date_types as $date_type => $info) {
     system_date_format_type_save($info);
   }
 
@@ -3484,12 +3540,13 @@ 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';
     }
-    if (!in_array($module_format['type'], array_keys($types))) {
+    if (!in_array($module_format['type'], array_keys($date_types))) {
       continue;
     }
     if (!isset($date_formats[$module_format['type']])) {
@@ -3498,7 +3555,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.
@@ -3514,20 +3571,20 @@ function _system_date_formats_build() {
     if (!isset($date_formats[$record->type])) {
       $date_formats[$record->type] = array();
     }
-    $format = (array) $record;
-    $format['is_new'] = FALSE; // It's in the db, so override this setting.
+    $date_format = (array) $record;
+    $date_format['is_new'] = FALSE; // It's in the db, so override this setting.
     // If this format not already present, add it to the array.
     if (!isset($date_formats[$record->type][$record->format])) {
-      $format['module'] = '';
-      $format['locales'] = array($record->language);
-      $date_formats[$record->type][$record->format] = $format;
+      $date_format['module'] = '';
+      $date_format['locales'] = array($record->language);
+      $date_formats[$record->type][$record->format] = $date_format;
     }
     // Format already present, so merge in settings.
     else {
       if (!empty($record->language)) {
-        $format['locales'] = array_merge($date_formats[$record->type][$record->format]['locales'], array($record->language));
+        $date_format['locales'] = array_merge($date_formats[$record->type][$record->format]['locales'], array($record->language));
       }
-      $date_formats[$record->type][$record->format] = array_merge($date_formats[$record->type][$record->format], $format);
+      $date_formats[$record->type][$record->format] = array_merge($date_formats[$record->type][$record->format], $date_format);
     }
   }
 
@@ -3538,67 +3595,81 @@ 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 $date_type
+ *   A date type array containing the following keys:
+ *   - type: A string containing the machine-readable name of the date type.
+ *   - title: A string containing the user interface 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 does not exist
+ *     in the database yet.
+ */
+function system_date_format_type_save($date_type) {
+  $info = array();
+  $info['type'] = $date_type['type'];
+  $info['title'] = $date_type['title'];
+  $info['locked'] = $date_type['locked'];
 
   // Update date_format table.
-  if (!empty($date_format_type['is_new'])) {
-    drupal_write_record('date_format_type', $type);
+  if (!empty($date_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 $date_type
+ *   A string containing the machine-readable name of the date type.
  */
-function system_date_format_type_delete($date_format_type) {
+function system_date_format_type_delete($date_type) {
   db_delete('date_formats')
-    ->condition('type', $date_format_type)
+    ->condition('type', $date_type)
     ->execute();
   db_delete('date_format_type')
-    ->condition('type', $date_format_type)
+    ->condition('type', $date_type)
     ->execute();
   db_delete('date_format_locale')
-    ->condition('type', $date_format_type)
+    ->condition('type', $date_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: A string containing the name of the date type this format is
+ *     associated with.
+ *   - format: A 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 with the specified date format 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');
@@ -3624,10 +3695,10 @@ function system_date_format_save($date_f
 }
 
 /**
- * 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')