environments.module

<?php

/**
 * @file
 * Environments module.
 */

/**
 * Environment alias max length, used in a few places.
 */
define('ENVIRONMENTS_ALIAS_MAXLENGTH', 12);

/**
 * Implements hook_permission().
 */
function environments_permission() {
  return array(
    'administer environments' => array(
      'title' => t('Administer Site Environments'),
      'description' => t('Administer the Environments module.'),
      'restrict access' => TRUE,
    ),
    'view environments notifications' => array(
      'title' => t('View Environments notifications'),
      'description' => t('View notifications about what the current environment is.'),
    ),
  );
}

/**
 * Implements hook_menu().
 */
function environments_menu() {
  $items = array();

  // Current environment settings.
  $items['admin/config/system/environments'] = array(
    'title' => 'Site environment',
    'description' => 'Manage the current site environment.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('environments_form_site'),
    'access arguments' => array('administer environments'),
    'file' => 'environments.admin.inc',
  );

  // Confirm environment change.
  $items['admin/config/system/environments/confirm/%'] = array(
    'title' => 'Confirm site environment change',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('environments_form_site_confirm', 5),
    'access arguments' => array('administer environments'),
    'file' => 'environments.admin.inc',
  );

  // Environments summary page.
  $items['admin/config/development/environments/summary'] = array(
    'title' => 'Summary',
    'page callback' => 'environments_page_summary',
    'access arguments' => array('administer environments'),
    'file' => 'environments.admin.inc',
    'type' => MENU_LOCAL_TASK,
    'weight' => 99,
  );

  // Shortcut to summary under Reports.
  $items['admin/reports/environments'] = array(
    'title' => 'Environments',
    'page callback' => 'drupal_goto',
    'page arguments' => array('admin/config/development/environments/summary'),
    'access arguments' => array('administer environments'),
  );

  return $items;
}

/**
 * Implements hook_menu_alter().
 */
function environments_menu_alter(&$items) {
  if (isset($items['admin/config/development/environments/list'])) {
    $items['admin/config/development/environments/list']['title'] = t('Environments');
  }
}

/**
 * Implements hook_help().
 */
function environments_help($path, $arg) {
  switch ($path) {
    case 'admin/help#environments':
      $path = drupal_get_path('module', 'environments');
      return file_get_contents("{$path}/docs/index.html");

    case 'admin/config/system/environments':
      return t('Here you can view and change the current environment, as well as manage other settings. To manage defined environments, go <a href="!url">here</a>.', array('!url' => url('admin/config/development/environments', array('absolute' => TRUE))));

    case 'admin/config/development/environments':
      return t('Here you can manage your environments and tasks. To change the current environment or manage other settings, go <a href="!url">here</a>.', array('!url' => url('admin/config/system/environments', array('absolute' => TRUE))));

    case 'admin/config/development/environments/list/%/tasks':
      return t('Here you can add to and manage all of an environment\'s tasks. <strong>NOTE</strong>: The order in which tasks appear is the exact order in which they will run. Use the handles on the left of each one to drag them around and re-order them and then press the "Update Order" button to save the changes.');

    case 'admin/config/development/environments/summary':
      return t("Here you can get a bird's eye view if your current site Environment and all available Environments and Task Bundles.");
  }
}

/**
 * Implements hook_form_alter().
 *
 * Alter the CTools Export UI form for our exportables to make them look more
 * like other Drupal forms.
 */
function environments_form_ctools_export_ui_edit_item_form_alter(&$form, &$form_state) {
  $plugins = array(
    'environments',
    'environments_bundles',
  );

  if (in_array($form_state['plugin']['name'], $plugins)) {
    $form['actions'] = array(
      '#type' => 'actions',
    );

    foreach (element_children($form['buttons']) as $button) {
      $form['actions'][$button] = $form['buttons'][$button];
      unset($form['buttons'][$button]);
    }

    unset($form['buttons']);
  }
}

/**
 * Helper function to add tasks to the batch.
 *
 * @param object $object
 *   Either an environment object or a task bundle object.
 * @param array $operations
 *   The array of operations to add to the batch.
 *
 * @see environments_set()
 */
function _environments_process_tasks($object, &$operations) {
  if (is_array($object->tasks)) {
    // Add tasks in order. We use a dispatcher function to allow operation
    // callbacks to live anywhere and not have to worry about specifying the
    // file right now.
    foreach (element_children($object->tasks, TRUE) as $task) {
      $task_info = $object->tasks[$task];
      $operations[] = array(
        '_environments_task_dispatcher',
        array($task_info),
      );
    }
  }
}

/**
 * Set the current environment.
 *
 * @param string $env
 *   An environment machine_name.
 */
function environments_set($env) {
  if ($environment = environments_load($env)) {
    $operations = array();

    // Process our tasks.
    _environments_process_tasks($environment, $operations);

    // Always run our cleanup operation last to set the context for status
    // messages and then flush caches for the grand finale.
    $operations[] = array(
      '_environments_task_cleanup',
      array(t('Cleaning up.'), $env),
    );

    // Setup batch.
    $batch = array(
      'title' => t('Setting up environment.'),
      'operations' => $operations,
      'finished' => '_environments_task_finished',
      'init_message' => t('Preparing to set environment.'),
      'progress_message' => t('Processed @current out of @total tasks.'),
      'error_message' => t('Error setting environent.'),
      'file' => drupal_get_path('module', 'environments') . '/environments.batch.inc',
    );

    batch_set($batch);
    _environments_process_batch($batch, 'admin/config/system/environments');
  }
  else {
    drupal_set_message(t('Trying to set invalid environment: %name', array('%name' => $env)), 'error', FALSE);
    watchdog('environments', 'Trying to set invalid environment: %name', array('%name' => $env), WATCHDOG_ERROR);
  }
}

/**
 * Helper function to process batch jobs.
 *
 * @param array $batch
 *   The batch definition.
 * @param string $redirect
 *   The url to redirect to once batch is finished.
 */
function _environments_process_batch($batch, $redirect = NULL) {
  // If running through CLI, process batch using Drush.
  if (php_sapi_name() === 'cli' && function_exists('drush_backend_batch_process')) {
    $batch =& batch_get();
    $batch['progressive'] = FALSE;
    drush_backend_batch_process();
  }
  else {
    batch_process($redirect);
  }
}

/**
 * Unset the current environment.
 */
function environments_unset() {
  variable_set('environments_env', '');
  watchdog('environments', 'Environment unset.', array(), WATCHDOG_INFO);
}

/**
 * Implements hook_page_build().
 */
function environments_page_build(&$page) {
  if ($env = variable_get('environments_env')) {
    if ($environment = environments_load($env)) {
      // Check if we want to notify in this environment.
      if ($environment->settings['notify']) {
        // Check whether user has access to view notifications. This is done so
        // late because it's the most expensive check we do, so we try to avoid
        // it whenver possible.
        if (user_access('view environments notifications')) {
          $path = drupal_get_path('module', 'environments');

          $page['page_top']['environments'] = array(
            '#theme' => 'environments_banner',
            '#environment' => $env,
          );

          // Include default styles.
          if (variable_get('environments_css', TRUE)) {
            $page['page_top']['environments']['#attached']['css'][] = $path . '/assets/css/environments.css';
          }

          // Include default scripts.
          if (variable_get('environments_js', TRUE)) {
            $page['page_top']['environments']['#attached']['js'][] = $path . '/assets/js/environments.js';
          }
        }
      }
    }
  }
}

/**
 * Implements hook_theme().
 */
function environments_theme() {
  return array(
    'environments_banner' => array(
      'template' => 'templates/banner',
      'file' => 'environments.theme.inc',
      'variables' => array(
        'environment' => '',
      ),
    ),
    'environments_task_form' => array(
      'render element' => 'form',
      'file' => 'environments.theme.inc',
    ),
  );
}

/**
 * Implements hook_ctools_plugin_directory().
 */
function environments_ctools_plugin_directory($module, $type) {
  if ($type === 'export_ui') {
    return 'plugins/export_ui';
  }
  elseif ($type === 'environments_task') {
    return 'plugins/environments_task';
  }
}

/**
 * Implements hook_ctools_plugin_type().
 */
function environments_ctools_plugin_type() {
  return array(
    'environments_task' => array(
      'cache' => TRUE,
      'defaults' => array(
        // Administrative title.
        'admin_title' => '',
        // Callback to execute.
        'task_callback' => '',
        // Optional. An array of task-specific settings.
        'settings' => array(),
        // Optional. Settings form callback.
        'settings_callback' => '',
        // Optional. Settings summary callback.
        'summary_callback' => '',
      ),
      'use hooks' => FALSE,
    ),
  );
}

/**
 * Implements hook_ctools_plugin_api().
 */
function environments_ctools_plugin_api($module, $api) {
  if ($module === 'environments' && $api === 'environments_task') {
    return array('version' => 1);
  }
}

/**
 * Fetch data on a single environment task.
 *
 * @param string $task
 *   Name of a task.
 *
 * @return array
 *   An array of environment task data.
 */
function environments_get_task($task) {
  ctools_include('plugins');
  return ctools_get_plugins('environments', 'environments_task', $task);
}

/**
 * Fetch data on all environment tasks.
 *
 * @return array
 *   An array with all data for all environment tasks.
 */
function environments_get_tasks() {
  ctools_include('plugins');
  return ctools_get_plugins('environments', 'environments_task');
}

/**
 * Create a new environment object.
 *
 * Note that this function does not save the environment to the database.
 *
 * @param array $values
 *   An array of values which which to initialize this environment.
 *
 * @see environments_form_edit()
 * @see environments_save()
 */
function environments_create($values = array()) {
  ctools_include('export');
  $environment = ctools_export_crud_new('environments');

  // Default name.
  if (isset($values['name'])) {
    $environment->name = $values['name'];
  }

  // Default title.
  if (isset($values['admin_title'])) {
    $environment->admin_title = $values['admin_title'];
  }

  // Default alias.
  if (isset($values['alias'])) {
    $environment->alias = $values['alias'];
  }

  // Default settings.
  $environment->settings = array(
    'notify' => TRUE,
  );

  if (isset($values['setings']) and is_array($values['settings'])) {
    $environment->settings = array_merge($environment->settings, $values['settings']);
  }

  // Default tasks.
  $environment->tasks = array();

  if (isset($values['tasks']) and is_array($values['tasks'])) {
    $environment->tasks = array_merge($values['tasks'], $environment->tasks);
  }

  return $environment;
}

/**
 * Fetches all environments from the database and returns them as an array.
 *
 * @return array
 *   An associative array.
 */
function environments_load_all() {
  ctools_include('export');
  return ctools_export_crud_load_all('environments');
}

/**
 * Load a given environment.
 *
 * @param string $environment_name
 *   The environment's name.
 *
 * @return stdClass|NULL
 *   The fully-loaded environment object or NULL if it couldn't be loaded.
 */
function environments_load($environment_name) {
  ctools_include('export');
  return ctools_export_crud_load('environments', $environment_name);
}

/**
 * Checks whether an environment with the given name already exists.
 *
 * @param string $environment_name
 *   The environment's name.
 *
 * @return bool
 *   TRUE if there exists an environment with the give name, FALSE otherwise.
 */
function environments_exists($environment_name) {
  ctools_include('export');
  $environment = ctools_export_crud_load('environments', $environment_name);
  return isset($environment->name);
}

/**
 * Saves the given environment to the database.
 *
 * @param object $environment
 *   The environment to save.
 *
 * @return object|boolean
 *   Failure to write a record will return FALSE. Otherwise SAVED_NEW or
 *   SAVED_UPDATED is returned depending on the operation performed. The
 *   $object parameter contains values for any serial fields defined.
 */
function environments_save(&$environment) {
  ctools_include('export');
  return ctools_export_crud_save('environments', $environment);
}

/**
 * Deletes the given environment from the database.
 *
 * @param object $environment
 *   The environment object to delete.
 */
function environments_delete($environment) {
  ctools_include('export');
  return ctools_export_crud_delete('environments', $environment);
}

/**
 * Helper function to generate generic task summaries.
 *
 * @param array $task
 *   A task definition.
 *
 * @return array
 *   An array of summary items.
 */
function environments_default_summary(array $task) {
  $settings_summary = array();

  $value_type = array_key_exists('value_type', $task['settings'])
    ? $task['settings']['value_type']
    : FALSE;

  foreach ($task['settings'] as $name => $value) {
    if (is_array($value)) {
      $value = implode(', ', $value);
    }
    else {
      if ($name === 'value' && $value_type) {
        if ($value_type === 'string') {
          $value = "\"{$value}\"";
        }
        // Boolean values are true/false.
        elseif (is_bool($value)) {
          $value_string = $value ? t('True') : t('False');
          $value = "<em>{$value_string}</em>";
        }
      }
      // Boolean settings are yes/no.
      elseif (is_bool($value)) {
        $value_string = $value ? t('Yes') : t('No');
        $value = "<em>{$value_string}</em>";
      }
    }

    // Give the setting a nice "human" label.
    $label = drupal_ucfirst(str_replace('_', ' ', $name));
    $settings_summary[] = "<strong>{$label}:</strong> {$value}";
  }

  return $settings_summary;
}

/**
 * Helper function to format module names for task summaries.
 *
 * @param array $settings
 *   An array of task settings.
 *
 * @return string
 *   A formatted string.
 *
 * @see environments_task_features_revert_summary()
 * @see environments_task_module_disable_summary()
 * @see environments_task_module_enable_summary()
 * @see environments_task_module_uninstall_summary()
 */
function _environments_module_task_summary(array $settings) {
  $return = '<em>none</em>';

  if (isset($settings['modules']) && is_array($settings['modules']) && !empty($settings['modules'])) {
    $temp = array();
    $module_map = _environments_get_modules();

    foreach ($settings['modules'] as $module) {
      if (array_key_exists($module, $module_map)) {
        $temp_string = "{$module_map[$module]}";

        if (variable_get('environments_detailed_summaries', TRUE)) {
          $temp_string .= " ({$module})";
        }

        $temp[] = $temp_string;
      }
      else {
        $temp[] = $module;
      }
    }

    $return = implode(', ', $temp);
  }

  return $return;
}

/**
 * Returns all available Drupal modules.
 *
 * Used by the "module_enable" and "module_disable" tasks. This is as a
 * lightweight replacement for using Drupal core APIs.
 *
 * @return array
 *   An array of module names, keyed by machine_name.
 */
function _environments_get_modules() {
  static $modules = array();

  if (empty($modules)) {
    // No value added by using DBTNG.
    $result = db_query("SELECT name, info FROM {system} ORDER BY name ASC");
    foreach ($result->fetchAll() as $row) {
      $info = unserialize($row->info);

      if (!isset($info['hidden']) || !$info['hidden']) {
        $modules[$row->name] = $info['name'];
      }
    }
  }

  return $modules;
}

/**
 * Returns all defined Drupal variables.
 *
 * Used by the "variable_set" and "variable_del" tasks. This is as a lightweight
 * replacement for using Drupal core APIs.
 *
 * @return array
 *   An array of variable names.
 */
function _environments_get_variables() {
  static $variables = array();

  if (empty($variables)) {
    // No value added by using DBTNG.
    $result = db_query("SELECT name FROM {variable} ORDER BY name ASC");
    $result = $result->fetchAllAssoc('name');
    $variables = array_keys($result);
  }

  return $variables;
}

/**
 * Returns all available Migrations.
 *
 * Used by the "migrate_import" and "migrate_rollback" tasks.
 *
 * @return array
 *   An array of migration names, keyed by machine_name.
 */
function _environments_get_migrations() {
  static $migrations = array();

  if (empty($migrations) && function_exists('migrate_migrations')) {
    // Load all available migrations.
    $loaded_migrations = migrate_migrations(TRUE);

    foreach ($loaded_migrations as $machine_name => $migration) {
      $migrations[$machine_name] = $machine_name;
    }
  }

  return $migrations;
}