cm_tools.module

<?php

/**
 * @file
 * The Computerminds tools module.
 *
 * We'll try to keep this file as lean as possible, and do as much as possible
 * in includes.
 *
 * This file contains hook implementations and helpers likely to be used on
 * every page request.
 */

include_once 'cm_tools.element.inc';

/**
 * Include .inc files as necessary.
 *
 * This fuction is helpful for including .inc files for your module. The
 * general case is including cm_tools helper functions like this:
 *
 * @code
 * cm_tools_include('profile');
 * @endcode
 *
 * @param string $file
 *   The base file name to be included.
 * @param string $module
 *   Optional module containing the include.
 * @param string $dir
 *   Optional subdirectory containing the include file.
 */
function cm_tools_include($file, $module = 'cm_tools', $dir = 'includes') {
  static $used = array();

  $dir = '/' . ($dir ? $dir . '/' : '');

  if (!isset($used[$module][$dir][$file])) {
    require_once DRUPAL_ROOT . '/' . drupal_get_path('module', $module) . "$dir$file.inc";
    $used[$module][$dir][$file] = TRUE;
  }
}

/**
 * Include .inc files in a form context.
 *
 * This is a variant of cm_tools_include that will save information in the
 * the form_state so that cached forms will properly include things.
 */
function cm_tools_form_include(&$form_state, $file, $module = 'cm_tools', $dir = 'includes') {
  $dir = '/' . ($dir ? $dir . '/' : '');
  form_load_include($form_state, 'inc', $module, $dir . $file);
}

/**
 * Implements hook_permission().
 */
function cm_tools_permission() {
  return array(
    'preserve during sanitization' => array(
      'title' => t('Preserve during SQL Sanitization'),
      'description' => t('Do not change users with this permission when sanitizing the database using Drush.'),
    ),
  );
}

/**
 * Implements hook_menu().
 */
function cm_tools_menu() {
  $items['cm_tools/monitoring/%'] = array(
    'page callback' => 'cm_tools_monitoring_page_callback',
    'access callback' => 'cm_tools_monitoring_access_callback',
    'access arguments' => array(2),
  );

  return $items;
}

/**
 * Implements hook_init().
 */
function cm_tools_init() {
  // Our monitoring page is never in maintenance mode.
  if ($_GET['q'] === 'cm_tools/monitoring/' . cm_tools_get_uptime_path_token()) {
    $GLOBALS['conf']['maintenance_mode'] = 0;
  }
}

/**
 * Access callback for the CM Tools monitoring page.
 *
 * @param string $token
 *   The token to check.
 *
 * @return bool
 *   TRUE if the token matches the one stored for this site. FALSE otherwise.
 */
function cm_tools_monitoring_access_callback($token) {
  return $token === cm_tools_get_uptime_path_token();
}

/**
 * Page callback for the monitoring page.
 */
function cm_tools_monitoring_page_callback() {
  // @todo: We could check to see if Memcache etc. are configured/functioning.
  drupal_page_is_cacheable(FALSE);
  // Print something unlikely to be printed by e.g. Apache error pages.
  print sha1(__FUNCTION__ . cm_tools_get_uptime_path_token());
  print "\n";
  print date('c');
  drupal_exit();
}

/**
 * Get a stable token for use in a path that is unique to this site.
 *
 * @return string
 *   The path token.
 */
function cm_tools_get_uptime_path_token() {
  if ($token = variable_get('cm_tools_get_uptime_path_token')) {
    return $token;
  }
  else {
    $token = drupal_random_key(64);
    variable_set('cm_tools_get_uptime_path_token', $token);
    return $token;
  }
}

/**
 * Inserts one or more suggestions into a theme_hook_suggestions array.
 *
 * @param array $haystack
 *   The $vars['theme_hook_suggestions'] array. It is modified by reference.
 * @param string|array $insert_value
 *   String value after which to insert $suggestions. May also be an array of
 *   suggested values in which case the first one to be found will be used.
 * @param string|array $suggestions
 *   A single new suggestion, or array of new suggestions to insert.
 * @param bool $insert_before
 *   (Optional) Change the behaviour of this function to insert *before*
 *   $insert_value instead of after it.
 * @param bool|true $append_on_fail
 *   (Optional) By default this function will append the $suggestions on the end
 *   of $haystack if $insert_value could not be found. Pass FALSE here to stop
 *   this and make this function return FALSE in this case.
 *
 * @return bool
 *   Success, either TRUE or FALSE.
 */
function cm_tools_insert_theme_hook_suggestion(array &$haystack, $insert_value, $suggestions, $insert_before = FALSE, $append_on_fail = TRUE) {

  if (!is_array($insert_value)) {
    $insert_value = array($insert_value);
  }

  $success = FALSE;
  foreach ($insert_value as $v) {
    if (cm_tools_array_insert_at_value($haystack, $v, $suggestions, $insert_before, FALSE)) {
      $success = TRUE;
      break;
    }
  }

  if (!$success && $append_on_fail) {
    if (!is_array($suggestions)) {
      $suggestions = array($suggestions);
    }
    $haystack = array_merge(array_values($haystack), array_values($suggestions));
    $success = TRUE;
  }

  return $success;
}

/**
 * Renames an array key while leaving it in exactly the same place in the array.
 *
 * @param array $haystack
 *   The array. This is modified by reference.
 * @param int|string $key
 *   The key to rename.
 * @param int|string $new_key
 *   The new name for the key. If this already exists in the array it will be
 *   overwritten.
 *
 * @return bool
 *   Success, either TRUE or FALSE.
 */
function cm_tools_array_rename_key(array &$haystack, $key, $new_key) {
  $success = FALSE;

  if (isset($haystack[$key])) {
    $insertion = array(
      $new_key => $haystack[$key],
    );
    if ($success = cm_tools_array_insert_at_key($haystack, $key, $insertion)) {
      if ($key !== $new_key) {
        unset($haystack[$key]);
      }
    }
  }

  return $success;
}

/**
 * Inserts a new element into an array, just after the one with the given value.
 *
 * The insert value is found by *strict* comparison. If multiple values are
 * found the insertion will be made next to the first occurance only.
 *
 * @param array $haystack
 *   The array. This is modified by reference.
 * @param mixed $insert_value
 *   Array value after which to insert $insertion. A *strict* comparison is
 *   performed when searching for this value.
 * @param mixed $insertions
 *   Array of new values to insert into the array. If $preserve_keys is TRUE and
 *   an element already exists in the array with the same key as one you are
 *   inserting, the old one(s) will removed. If this parameter is not an array
 *   it will be inserted into the array with the lowest available numeric key.
 * @param bool $insert_before
 *   (Optional) Change the behaviour of this function to insert *before*
 *   $insert_value instead of after it.
 * @param bool $preserve_keys
 *   (Optional) By default this function ignores keys, giving everything a new
 *   numeric index. Pass TRUE here to indicate that all keys should be
 *   preserved.
 *
 * @return bool
 *   Success, either TRUE or FALSE.
 */
function cm_tools_array_insert_at_value(array &$haystack, $insert_value, $insertions, $insert_before = FALSE, $preserve_keys = FALSE) {
  $success = FALSE;
  $insert_key = array_search($insert_value, $haystack, TRUE);
  if ($insert_key !== FALSE) {
    $success = cm_tools_array_insert_at_key($haystack, $insert_key, $insertions, $insert_before, $preserve_keys);
  }
  return $success;
}

/**
 * Inserts a new element into an array, just after the one with the given key.
 *
 * The insert key is found by *strict* comparison.
 *
 * @param array $haystack
 *   The array. This is modified by reference.
 * @param int|string|array $insert_key
 *   Array key after which to insert $insertion. This can also be an array of
 *   suggested keys, in which case each will be looked for in turn and the
 *   first existing one will be used. A *strict* comparison is performed when
 *   searching for this key.
 * @param mixed $insertions
 *   Array of new values to insert into the array. Unless $preserve_keys is
 *   FALSE if an element already exists in the array with the same key as one
 *   you are inserting, the old one(s) will removed. If this parameter is not an
 *   array it will be inserted into the array with the lowest available numeric
 *   key.
 * @param bool $insert_before
 *   (Optional) Change the behaviour of this function to insert *before*
 *   $insert_key instead of after it.
 * @param bool|true $preserve_keys
 *   (Optional) By default this function always preserves keys, even for
 *   numerically-indexed arrays. Pass FALSE here if using a numerically-indexed
 *   array and you don't want to overwrite elements.
 *
 * @return bool
 *   Success, either TRUE or FALSE.
 */
function cm_tools_array_insert_at_key(array &$haystack, $insert_key, $insertions, $insert_before = FALSE, $preserve_keys = TRUE) {

  $success = FALSE;

  if (!is_array($insert_key)) {
    $insert_key = array($insert_key);
  }

  $haystack_keys = array_keys($haystack);
  $offset = FALSE;
  while (count($insert_key) && $offset === FALSE) {
    $loc = array_shift($insert_key);
    $offset = array_search($loc, $haystack_keys, TRUE);
  }

  if ($offset !== FALSE) {
    if ($insert_before) {
      $offset = $offset - 1;
    }
    $success = cm_tools_array_insert_at_offset($haystack, $offset + 1, $insertions, $preserve_keys);
  }

  return $success;
}

/**
 * Inserts a new element at an offset in an array.
 *
 * @param array $haystack
 *   The array. This is modified by reference.
 * @param int $offset
 *   Offset after which to insert $insertion.
 * @param mixed $insertions
 *   Array of new values to insert into the array. If $preserve_keys is TRUE and
 *   an element already exists in the array with the same key as one you are
 *   inserting, the old one(s) will removed. If this parameter is not an array
 *   it will be inserted into the array with the lowest available numeric key.
 * @param bool $preserve_keys
 *   (Optional) By default this function ignores keys, giving everything a new
 *   numeric index. Pass TRUE here to indicate that all keys should be
 *   preserved.
 *
 * @return bool
 *   Success, either TRUE or FALSE.
 */
function cm_tools_array_insert_at_offset(array &$haystack, $offset, $insertions, $preserve_keys = FALSE) {

  $success = FALSE;

  if (!is_int($offset)) {
    return FALSE;
  }

  if (!$preserve_keys) {
    $haystack = array_values($haystack);
  }

  // Insertions not given as an array. Give it the lowest available numeric key.
  if (!is_array($insertions)) {
    $numeric_keys = array_filter(array_keys($haystack), 'is_numeric');
    $unique_key = !empty($numeric_keys) ? max($numeric_keys) + 1 : 0;
    $insertions = array($unique_key => $insertions);
  }

  if (!$preserve_keys) {
    $insertions = array_values($insertions);
  }

  // Wipe out any keys we're about to overwrite, and ensure we modify the
  // $offset to take into account the changed $haystack.
  if ($preserve_keys) {
    $o = 0;
    foreach (array_keys($haystack) as $k) {
      if (isset($insertions[$k])) {
        if ($o < $offset) {
          $offset--;
        }
        unset($haystack[$k]);
      }
      $o++;
    }
  }

  $before = array_slice($haystack, 0, $offset, TRUE);
  $after = array_slice($haystack, $offset, count($haystack), TRUE);

  if (!$preserve_keys) {
    $haystack = array_merge($before, $insertions, $after);
    $success = TRUE;
  }
  else {
    $keys = array_merge(array_keys($before), array_keys($insertions), array_keys($after));
    $values = array_merge($before, $insertions, $after);
    $haystack = array_combine($keys, $values);
    $success = TRUE;
  }

  return $success;
}

/**
 * Remove element(s) with given value(s) from an array.
 *
 * @param array $haystack
 *   The array. This is modified by reference.
 * @param string|array $values
 *   A string value or array of values to remove from the array.
 */
function cm_tools_array_remove_values(array &$haystack, $values) {
  // Make values an array.
  if (is_string($values)) {
    $values = array($values);
  }

  foreach ($values as $value_to_remove) {
    $key = array_search($value_to_remove, $haystack);
    if ($key !== FALSE) {
      unset($haystack[$key]);
    }
  }
}

/**
 * Sort an array by values using a user-defined comparison function.
 *
 * However, unlike usort, equal values maintain their order.
 *
 * The comparison function must return an integer less than, equal to, or
 * greater than zero if the first argument is considered to be
 * respectively less than, equal to, or greater than the second.
 *
 * @param array $array
 *   The input array.
 * @param callable $cmp_function
 *   A comparision function that will abide by the usual semantics of a
 *   comparision callback. See @usort.
 *
 * @return int
 *   The result of the sort.
 */
function cm_tools_stable_usort(array &$array, callable $cmp_function) {
  $index = 0;
  foreach ($array as &$item) {
    $item = array($index++, $item);
  }
  $result = usort($array, function ($a, $b) use ($cmp_function) {
    $result = call_user_func($cmp_function, $a[1], $b[1]);
    return $result == 0 ? $a[0] - $b[0] : $result;
  });
  foreach ($array as &$item) {
    $item = $item[1];
  }
  return $result;
}

/**
 * Sort an array by user-defined comparison function, preserving indexes.
 *
 * However, unlike uasort, equal values maintain their order.
 *
 * The comparison function must return an integer less than, equal to, or
 * greater than zero if the first argument is considered to be
 * respectively less than, equal to, or greater than the second.
 *
 * @param array $array
 *   The input array.
 * @param callable $cmp_function
 *   A comparision function that will abide by the usual semantics of a
 *   comparision callback. See @usort.
 *
 * @return int
 *   The result of the sort.
 */
function cm_tools_stable_uasort(array &$array, callable $cmp_function) {
  $index = 0;
  foreach ($array as &$item) {
    $item = array($index++, $item);
  }
  $result = uasort($array, function ($a, $b) use ($cmp_function) {
    $result = call_user_func($cmp_function, $a[1], $b[1]);
    return $result == 0 ? $a[0] - $b[0] : $result;
  });
  foreach ($array as &$item) {
    $item = $item[1];
  }
  return $result;
}

/**
 * Implements hook_theme().
 */
function cm_tools_theme($existing, $type, $theme, $path) {
  $items = array(
    'cm_tools_html_wrapper' => array(
      'render element' => 'element',
      'file' => 'cm_tools.theme.inc',
    ),
  );
  return $items;
}

/**
 * Implements hook_preprocess_entity().
 *
 * We add in a full and comprehensive selection of theme hook suggestions,
 * consistent across entities. This transforms the default suggestions from:
 *
 *   1. entitytype--id      (eg. node--34.tpl.php)
 *   2. entitytype--bundle  (eg. node--article.tpl.php)
 *   3. entitytype          (eg. node.tpl.php)
 *
 * To a more flexible:
 *
 *   1. entitytype--id--viewmode      (eg. node--34--teaser.tpl.php)
 *   2. entitytype--id                (eg. node--34.tpl.php)
 *   3. entitytype--bundle--viewmode  (eg. node--article--teaser.tpl.php)
 *   4. entitytype--viewmode          (eg. node--teaser.tpl.php)
 *   5. entitytype--bundle            (eg. node--article.tpl.php)
 *   6. entitytype                    (eg. node.tpl.php)
 *
 * We also some complementary classes to the entity template classes array,
 * in the event that only css is required.
 */
function cm_tools_preprocess_entity(&$vars, $hook, $suggestion_prefix = 'entity__') {

  $entity_type = $vars['entity_type'];

  $view_mode = isset($vars['view_mode']) ? $vars['view_mode'] : 'full';

  // Add a full selection of theme hook suggestions.
  if (isset($vars[$entity_type]) && is_object($vars[$entity_type])) {
    $entity = $vars[$entity_type];
    list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);

    if (empty($bundle)) {
      $bundle = $entity_type;
    }

    $entity_type = isset($vars['entity_type_theme_name']) ? $vars['entity_type_theme_name'] : $entity_type;

    // Ensure theme_hook_suggestions for id, bundle and view_mode.
    $suggestion = "{$entity_type}__{$bundle}";
    if (!in_array($suggestion, $vars['theme_hook_suggestions']) && !in_array($suggestion_prefix . $suggestion, $vars['theme_hook_suggestions'])) {
      array_unshift($vars['theme_hook_suggestions'], $suggestion_prefix . $suggestion);
    }
    $suggestion = "{$entity_type}__{$view_mode}";
    if (!in_array($suggestion, $vars['theme_hook_suggestions']) && !in_array($suggestion_prefix . $suggestion, $vars['theme_hook_suggestions'])) {
      cm_tools_insert_theme_hook_suggestion($vars['theme_hook_suggestions'], "{$entity_type}__{$bundle}", $suggestion_prefix . $suggestion);
    }
    $suggestion = "{$entity_type}__{$bundle}__{$view_mode}";
    if (!in_array($suggestion, $vars['theme_hook_suggestions']) && !in_array($suggestion_prefix . $suggestion, $vars['theme_hook_suggestions'])) {
      cm_tools_insert_theme_hook_suggestion($vars['theme_hook_suggestions'], "{$entity_type}__{$view_mode}", $suggestion_prefix . $suggestion);
    }
    $suggestion = "{$entity_type}__{$id}";
    if (!in_array($suggestion, $vars['theme_hook_suggestions']) && !in_array($suggestion_prefix . $suggestion, $vars['theme_hook_suggestions'])) {
      $vars['theme_hook_suggestions'][] = $suggestion_prefix . $suggestion;
    }
    $suggestion = "{$entity_type}__{$id}__{$view_mode}";
    if (!in_array($suggestion, $vars['theme_hook_suggestions']) && !in_array($suggestion_prefix . $suggestion, $vars['theme_hook_suggestions'])) {
      cm_tools_insert_theme_hook_suggestion($vars['theme_hook_suggestions'], "{$entity_type}__{$id}", $suggestion_prefix . $suggestion);
    }
  }

  // Add a class indicating view mode.
  $classes = array();
  $classes[] = drupal_clean_css_identifier("{$entity_type}-{$view_mode}");
  // Also add entity-bundle-view_mode combo.
  $classes[] = drupal_clean_css_identifier("{$entity_type}-{$bundle}-{$view_mode}");
  if (isset($vars['classes_array'])) {
    $vars['classes_array'] = array_merge($vars['classes_array'], $classes);
  }
  elseif (isset($vars['attributes_array'])) {
    $vars['attributes_array'] = array_merge_recursive($vars['attributes_array'], array('class' => $classes));
  }
  elseif (isset($vars['classes']) && is_string($vars['classes'])) {
    $vars['classes'] .= ' ' . implode(' ', $classes);
  }
}

/**
 * Implements hook_preprocess_comment().
 */
function cm_tools_preprocess_comment(&$vars, $hook) {
  $vars['entity_type'] = 'comment';
  if (isset($vars['elements']['#view_mode'])) {
    $vars['view_mode'] = $vars['elements']['#view_mode'];
  }
  cm_tools_preprocess_entity($vars, $hook, '');
}

/**
 * Implements hook_preprocess_node().
 */
function cm_tools_preprocess_node(&$vars, $hook) {
  $vars['entity_type'] = 'node';
  cm_tools_preprocess_entity($vars, $hook, '');
}

/**
 * Implements hook_preprocess_taxonomy_term().
 */
function cm_tools_preprocess_taxonomy_term(&$vars, $hook) {
  $vars['entity_type'] = 'taxonomy_term';
  $vars[$vars['entity_type']] = $vars['term'];
  cm_tools_preprocess_entity($vars, $hook, '');
}

/**
 * Implements hook_preprocess_taxonomy_vocabulary().
 */
function cm_tools_preprocess_taxonomy_vocabulary(&$vars, $hook) {
  $vars['entity_type'] = 'taxonomy_vocabulary';
  cm_tools_preprocess_entity($vars, $hook, '');
}

/**
 * Implements hook_preprocess_user_profile().
 */
function cm_tools_preprocess_user_profile(&$vars, $hook) {
  $vars['entity_type'] = 'user';
  $vars['entity_type_theme_name'] = 'user_profile';
  if (!isset($vars['view_mode'])) {
    $vars['view_mode'] = $vars['elements']['#view_mode'];
  }
  cm_tools_preprocess_entity($vars, $hook, '');
}

/**
 * Implements hook_views_plugins().
 */
function cm_tools_views_plugins() {
  module_load_include('inc', 'cm_tools', 'cm_tools.views');
  return _cm_tools_views_plugins();
}

/**
 * Implements hook_preprocess_page().
 */
function cm_tools_preprocess_page(&$vars) {

  // Allow drupal_add_region_content() to work everywhere, not just on the
  // maintenance page as per Drupal core.
  foreach (drupal_add_region_content() as $region => $contents) {

    // Standardize each item to a render array.
    foreach ($contents as $k => $content) {
      if (!is_array($content)) {
        $contents[$k] = array(
          '#type' => 'markup',
          '#markup' => $content,
        );
      }
    }

    // And add in the extra content.
    if (isset($vars['page'][$region])) {
      if (is_string($vars['page'][$region])) {
        $vars['page'][$region] .= drupal_render($contents);
      }
      else {
        $vars['page'][$region] = array_merge($vars['page'][$region], $contents);
      }
    }
    else {
      $vars['page'][$region] = $contents;
    }
  }
}

/**
 * Add an external JS file in a non-blocking manner, once per page.
 *
 * Ideally, use as an #attached callback to be caching-friendly, like so:
 *
 *   $render_array['#attached']['cm_tools_add_async_js'][] = array(<url>, <id>);
 *
 * @param string $script
 *   The URL of the script to load (schemeless/protocol relative are
 *   best, for avoiding mixed http/https content warnings).
 * @param string $id
 *   The id to give the script tag (to prevent multiple loads).
 */
function cm_tools_add_async_js($script = '', $id = '') {
  drupal_add_js('!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="' . $script . '";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","' . $id . '");',
    array('type' => 'inline', 'scope' => 'footer', 'weight' => 5)
  );
}