engines.inc

<?php

/**
 * @file
 * The drush engines API implementation and helpers.
 */

use Drush\Log\LogLevel;

/**
 * Obtain all engine types info and normalize with defaults.
 *
 * @see hook_drush_engine_type_info().
 */
function drush_get_engine_types_info() {
  $info = drush_command_invoke_all('drush_engine_type_info');
  foreach ($info as $type => $data) {
    $info[$type] += array(
      'description' => '',
      'option' => FALSE,
      'default' => NULL,
      'options' => array(),
      'sub-options' => array(),
      'config-aliases' => array(),
      'add-options-to-command' => FALSE,
      'combine-help' => FALSE,
    );
  }

  return $info;
}

/**
 * Return a structured array of engines of a specific type.
 *
 * Engines are pluggable subsystems. Each engine of a specific type will
 * implement the same set of API functions and perform the same high-level
 * task using a different backend or approach.
 *
 * This function/hook is useful when you have a selection of several mutually
 * exclusive options to present to a user to select from.
 *
 * Other commands are able to extend this list and provide their own engines.
 * The hook can return useful information to help users decide which engine
 * they need, such as description or list of available engine options.
 *
 * The engine path element will automatically default to a subdirectory (within
 * the directory of the commandfile that implemented the hook) with the name of
 * the type of engine - e.g. an engine "wget" of type "handler" provided by
 * the "pm" commandfile would automatically be found if the file
 * "pm/handler/wget.inc" exists and a specific path is not provided.
 *
 * @param $engine_type
 *   The type of engine.
 *
 * @return
 *   A structured array of engines.
 */
function drush_get_engines($engine_type) {
  $info = drush_get_engine_types_info();
  if (!isset($info[$engine_type])) {
    return drush_set_error('DRUSH_UNKNOWN_ENGINE_TYPE', dt('Unknown engine type !engine_type', array('!engine_type' => $engine_type)));
  }

  $engines = array(
    'info' => $info[$engine_type],
    'engines' => array(),
  );
  $list = drush_commandfile_list();
  $hook = 'drush_engine_' . str_replace('-', '_', $engine_type);
  foreach ($list as $commandfile => $path) {
    if (drush_command_hook($commandfile, $hook)) {
      $function = $commandfile . '_' . $hook;
      $result = $function();
      foreach ($result as $engine_name => $engine) {
        // Add some defaults.
        $engine += array(
          'commandfile' => $commandfile,
          'options' => array(),
          'sub-options' => array(),
          'drupal dependencies' => array(),
        );

        // Legacy engines live in a subdirectory
        // of the commandfile that declared them.
        $engine_path = sprintf("%s/%s", dirname($path), $engine_type);
        if (file_exists($engine_path)) {
          $engine['path'] = $engine_path;
        }
        // Build engine class name, in case the engine doesn't provide it.
        // The class name is based on the engine type and name, converted
        // from snake_case to CamelCase.
        // For example for type 'package_handler' and engine 'git_drupalorg'
        // the class is \Drush\PackageHandler\GitDrupalorg
        elseif (!isset($engine['class'])) {
          $parts = array();
          $parts[] = '\Drush';
          $parts[] = str_replace(' ', '', ucwords(strtr($engine_type, '_', ' ')));
          $parts[] = str_replace(' ', '', ucwords(strtr($engine_name, '_', ' ')));
          $engine['class'] = implode('\\', $parts);
        }

        $engines['engines'][$engine_name] = $engine;
      }
    }
  }

  return $engines;
}

/**
 * Take a look at all of the available engines,
 * and create topic commands for each one that
 * declares a topic.
 */
function drush_get_engine_topics() {
  $items = array();
  $info = drush_get_engine_types_info();
  foreach ($info as $engine => $data) {
    if (array_key_exists('topic', $data)) {
      $items[$data['topic']] = array(
        'description' => $data['description'],
        'hidden' => TRUE,
        'topic' => TRUE,
        'bootstrap' => DRUSH_BOOTSTRAP_DRUSH,
        'callback' => 'drush_engine_topic_command',
        'callback arguments' => array($engine),
      );
    }
  }
  return $items;
}

/**
 * Include, instantiate and validate command engines.
 *
 * @return FALSE if a engine doesn't validate.
 */
function drush_load_command_engines($command) {
  $result = TRUE;
  foreach ($command['engines'] as $engine_type => $config) {
    $result = drush_load_command_engine($command, $engine_type);
    // Stop loading engines if any of them fails.
    if ($result === FALSE) {
      break;
    }
  }
  return $result;
}

/**
 * Returns engine config supplied in the command definition.
 */
function drush_get_command_engine_config($command, $engine_type, $metadata = array()) {
  if (isset($command['engines'][$engine_type])) {
    $metadata = array_merge($metadata, $command['engines'][$engine_type]);
  }
  return $metadata;
}

/**
 * Selects and loads an engine implementing the given type.
 *
 * Loaded engines are stored as a context.
 */
function drush_load_command_engine($command, $engine_type, $metadata = array()) {
  drush_log(dt("Loading !engine engine.", array('!engine' => $engine_type), LogLevel::BOOTSTRAP));

  $config = drush_get_command_engine_config($command, $engine_type, $metadata);
  $engine_info = drush_get_engines($engine_type);
  $engine = drush_select_engine($config, $engine_info);
  $version = drush_drupal_major_version();

  $context = $engine_type . '_engine_' . $engine . '_' . $version;
  $instance = drush_get_context($context, FALSE);
  if ($instance != FALSE) {
    drush_set_engine($engine_type, $instance);
  }
  else {
    $instance = drush_load_engine($engine_type, $engine, $config);
    if ($instance == FALSE) {
      return FALSE;
    }
    drush_set_context($context, $instance);
  }
  return $instance;
}

/**
 * Add command structure info from each engine type back into the command.
 */
function drush_merge_engine_data(&$command) {
  // First remap engine data from the shortcut location
  // ($command['engine_type']) to the standard location
  // ($command['engines']['engine_type'])
  $info = drush_get_engine_types_info();
  foreach ($info as $engine_type => $info) {
    if (isset($command[$engine_type])) {
      $config = $command[$engine_type];
      foreach ($info['config-aliases'] as $engine_option_alias_name => $engine_option_standard_name) {
        if (array_key_exists($engine_option_alias_name, $config)) {
          $config[$engine_option_standard_name] = $config[$engine_option_alias_name];
          unset($config[$engine_option_alias_name]);
        }
      }
      // Convert single string values of 'require-engine-capability' to an array.
      if (isset($config['require-engine-capability']) && is_string($config['require-engine-capability'])) {
        $config['require-engine-capability'] = array($config['require-engine-capability']);
      }
      $command['engines'][$engine_type] = $config;
    }
  }

  foreach ($command['engines'] as $engine_type => $config) {
    // Normalize engines structure.
    if (!is_array($config)) {
      unset($command['engines'][$engine_type]);
      $command['engines'][$config] = array();
      $engine_type = $config;
    }

    // Get all implementations for this engine type.
    $engine_info = drush_get_engines($engine_type);
    if ($engine_info === FALSE) {
      return FALSE;
    }

    // Complete command-declared engine type with default info.
    $command['engines'][$engine_type] += $engine_info['info'];
    $config = $command['engines'][$engine_type];

    $engine_data = array();

    // If there's a single implementation for this engine type, it will be
    // loaded by default, and makes no sense to provide a command line option
    // to select the only flavor (ie. --release_info=updatexml), so we won't
    // add an option in this case.
    // Additionally, depending on the command, it may be convenient to extend
    // the command with the engine options.
    if (count($engine_info['engines']) == 1) {
      if ($config['add-options-to-command'] !== FALSE) {
        // Add options and suboptions of the engine type and
        // the sole implementation.
        $engine = key($engine_info['engines']);
        $data = $engine_info['engines'][$engine];
        $engine_data += array(
          'options' => $config['options'] + $data['options'],
          'sub-options' => $config['sub-options'] + $data['sub-options'],
        );
      }
    }
    // Otherwise, provide a command option to choose between engines and add
    // the engine options and sub-options.
    else {
      // Add engine type global options and suboptions.
      $engine_data += array(
        'options' => $config['options'],
        'sub-options' => $config['sub-options'],
      );

      // If the 'combine-help' flag is set in the engine config,
      // then we will combine all of the help items into the help
      // text for $config['option'].
      $combine_help = $config['combine-help'];
      $combine_help_data = array();

      // Process engines in order. First the default engine, the rest alphabetically.
      $default = drush_select_engine($config, $engine_info);
      $engines = array_keys($engine_info['engines']);
      asort($engines);
      array_unshift($engines, $default);
      $engines = array_unique($engines);
      foreach ($engines as $engine) {
        $data = $engine_info['engines'][$engine];
        // Check to see if the command requires any particular
        // capabilities.  If no capabilities are required, then
        // all engines are acceptable.
        $engine_is_usable = TRUE;
        if (array_key_exists('require-engine-capability', $config)) {
          // See if the engine declares that it provides any
          // capabilities.  If no capabilities are listed, then
          // it is assumed that the engine can satisfy all requirements.
          if (array_key_exists('engine-capabilities', $data)) {
            $engine_is_usable = FALSE;
            // If 'require-engine-capability' is TRUE instead of an array,
            // then only engines that are universal (do not declare any
            // particular capabilities) are usable.
            if (is_array($config['require-engine-capability'])) {
              foreach ($config['require-engine-capability'] as $required) {
                // We need an engine that provides any one of the requirements.
                if (in_array($required, $data['engine-capabilities'])) {
                  $engine_is_usable = TRUE;
                }
              }
            }
          }
        }
        if ($engine_is_usable) {
          $command['engines'][$engine_type]['usable'][] = $engine;
          if (!isset($data['hidden'])) {
            $option = $config['option'] . '=' . $engine;
            $engine_data['options'][$option]['description'] = array_key_exists('description', $data) ? $data['description'] : NULL;
            if ($combine_help) {
              $engine_data['options'][$option]['hidden'] = TRUE;
              if (drush_get_context('DRUSH_VERBOSE') || ($default == $engine) || !isset($data['verbose-only'])) {
                $combine_help_data[$engine] = $engine . ': ' . $data['description'];
              }
            }
            if (isset($data['options'])) {
              $engine_data['sub-options'][$option] = $data['options'];
            }
            if (isset($data['sub-options'])) {
              $engine_data['sub-options'] += $data['sub-options'];
            }
          }
        }
      }
      if (!empty($combine_help_data)) {
        $engine_selection_option = $config['option'];
        if (!is_array($engine_data['options'][$engine_selection_option])) {
          $engine_data['options'][$engine_selection_option] = array('description' => $config['options'][$engine_selection_option]);
        }
        if (drush_get_context('DRUSH_VERBOSE')) {
          $engine_data['options'][$engine_selection_option]['description'] .= "\n" . dt("All available values are:") . "\n - " . implode("\n - ", $combine_help_data) . "\n";
        }
        else {
          $engine_data['options'][$engine_selection_option]['description'] .= " " . dt("Available: ") . implode(', ', array_keys($combine_help_data)) . ". ";
        }
        $engine_data['options'][$engine_selection_option]['description'] .= dt("Default is !default.", array('!default' => $default));
      }
      else {
        // If the help options are not combined, then extend the
        // default engine description.
        $desc = $engine_info['engines'][$default]['description'];
        $engine_info['engines'][$default]['description'] = dt('Default !type engine.', array('!type' => $engine_type)) . ' ' . $desc;
      }
    }
    // This was simply array_merge_recursive($command, $engine_data), but this
    // function has an undesirable behavior when merging primative types.
    // If there is a 'key' => 'value' in $command, and the same 'key' => 'value'
    // exists in $engine data, then the result will be 'key' => array('value', 'value');.
    // This is NOT what we want, so we provide our own 'overlay' function instead.
    $command = _drush_array_overlay_recursive($command, $engine_data);
  }
}

// Works like array_merge_recursive(), but does not convert primative
// types into arrays.  Ever.
function _drush_array_overlay_recursive($a, $b) {
  foreach ($b as $key => $value) {
    if (!isset($a[$key]) || !is_array($a[$key])) {
      $a[$key] = $b[$key];
    }
    else {
      $a[$key] = _drush_array_overlay_recursive($a[$key], $b[$key]);
    }
  }
  return $a;
}

/**
 * Implementation of command hook for docs-output-formats
 */
function drush_engine_topic_command($engine) {
  $engine_instances = drush_get_engines($engine);
  $option = $engine_instances['info']['option'];

  if (isset($engine_instances['info']['topic-file'])) {
    // To do: put this file next to the commandfile that defines the
    // engine type, not in the core docs directory.
    $docs_dir = drush_get_context('DOC_PREFIX', DRUSH_BASE_PATH);
    $path = $engine_instances['info']['topic-file'];
    $docs_file = (drush_is_absolute_path($path) ? '' : $docs_dir . '/') . $path;
    $doc_text = drush_html_to_text(file_get_contents($docs_file));
  }
  elseif (isset($engine_instances['info']['topic-text'])) {
    $doc_text = $engine_instances['info']['topic-text'];
  }
  else {
    return drush_set_error('DRUSH_BAD_ENGINE_TOPIC', dt("The engine !engine did not define its topic command correctly.", array('!engine' => $engine)));
  }

  // Look at each instance of the engine; if it has an html
  // file in the the 'topics' folder named after itself, then
  // include the file contents in the engine topic text.
  $instances = $engine_instances['engines'];
  ksort($instances);
  foreach ($instances as $instance => $config) {
    if (isset($config['description'])) {
      $doc_text .= "\n\n::: --$option=$instance :::\n" . $config['description'];
      $path = $config['path'] . '/topics/' . $instance . '.html';
      if (file_exists($path)) {
        $doc_text .= "\n" . drush_html_to_text(file_get_contents($path));
      }
      $additional_topic_text = drush_command_invoke_all('drush_engine_topic_additional_text', $engine, $instance, $config);
      if (!empty($additional_topic_text)) {
        $doc_text .= "\n\n" . implode("\n\n", $additional_topic_text);
      }
    }
  }

  // Write the topic text to a file so that is can be paged
  $file = drush_save_data_to_temp_file($doc_text);
  drush_print_file($file);
}

/**
 * Selects an engine between the available ones.
 *
 * Precedence:
 *
 *  - preferred engine, if available.
 *  - user supplied engine via cli.
 *  - default engine from engine type / command declaration.
 *  - the first engine available.
 *
 * @param array $config
 *   Engine type configuration. My be overridden in command declaration.
 * @param array $engine_info
 *   Engine type declaration.
 * @param string $default
 *   Preferred engine.
 *
 * @return string
 *   Selected engine.
 */
function drush_select_engine($config, $engine_info, $preferred = NULL) {
  $engines = array_keys($engine_info['engines']);

  if (in_array($preferred, $engines)) {
    return $preferred;
  }

  if (!empty($config['option'])) {
    $engine = drush_get_option($config['option'], FALSE);
    if ($engine && in_array($engine, $engines)) {
      return $engine;
    }
  }

  if (isset($config['default']) && in_array($config['default'], $engines)) {
    return $config['default'];
  }

  return current($engines);
}

/**
 * Loads and validate an engine of the given type.
 *
 * @param string $type
 *   Engine type.
 * @param string $engine
 *   Engine name.
 * @param array $config
 *   Engine configuration. Tipically it comes from a command declaration.
 *
 * @return
 *   TRUE or instanced object of available class on success. FALSE on fail.
 */
function drush_load_engine($type, $engine, $config = array()) {
  $engine_info = drush_get_engines($type);
  $engine = drush_select_engine($config, $engine_info, $engine);
  $config['engine-info'] = $engine_info['engines'][$engine];

  // Check engine dependency on drupal modules before include.
  $dependencies = $config['engine-info']['drupal dependencies'];
  foreach ($dependencies as $dependency) {
    if (!drush_module_exists($dependency)) {
      return drush_set_error('DRUSH_ENGINE_DEPENDENCY_ERROR', dt('!engine_type: !engine engine needs the following modules installed/enabled to run: !dependencies.', array('!engine_type' => $type, '!engine' => $engine, '!dependencies' => implode(', ', $dependencies))));
    }
  }

  $result = drush_include_engine($type, $engine, $config);
  if (is_object($result)) {
    $valid = method_exists($result, 'validate') ? $result->validate() : TRUE;
    if ($valid) {
      drush_set_engine($type, $result);
    }
  }
  else {
    $function = strtr($type, '-', '_') . '_validate';
    $valid = function_exists($function) ? call_user_func($function) : TRUE;
  }
  if (!$valid) {
    return FALSE;
  }
  return $result;
}

/**
 * Include the engine code for a specific named engine of a certain type.
 *
 * If the engine type has implemented hook_drush_engine_$type the path to the
 * engine specified in the array will be used.
 *
 * If a class named in the form drush_$type_$engine exists, it will return an
 * instance of the class.
 *
 * @param string $type
 *   The type of engine.
 * @param string $engine
 *   The name for the engine to include.
 * @param array $config
 *   Parameters for the engine class constructor.
 *
 * @return
 *   TRUE or instanced object of available class on success. FALSE on fail.
 */
function drush_include_engine($type, $engine, $config = NULL) {
  $engine_info = drush_get_engines($type);

  // Pick the engine name that actually implements the requested engine.
  $engine = isset($engine_info['engines'][$engine]['implemented-by']) ? $engine_info['engines'][$engine]['implemented-by'] : $engine;

  // Legacy engines live in a subdirectory of the commandfile
  // that declares them. We need to explicitly include the file.
  if (isset($engine_info['engines'][$engine]['path'])) {
    $path = $engine_info['engines'][$engine]['path'];
    if (!drush_include($path, $engine)) {
      return drush_set_error('DRUSH_ENGINE_INCLUDE_FAILED', dt('Unable to include the !type engine !engine from !path.' , array('!path' => $path, '!type' => $type, '!engine' => $engine)));
    }
    // Legacy engines may be implemented in a magic class name.
    $class = 'drush_' . $type . '_' . str_replace('-', '_', $engine);
    if (class_exists($class)) {
      $instance = new $class($config);
      $instance->engine_type = $type;
      $instance->engine = $engine;
      return $instance;
    }

    return TRUE;
  }

  return drush_get_class($engine_info['engines'][$engine]['class'], array($type, $engine, $config));
}

/**
 * Return the engine of the specified type that was loaded by the Drush command.
 */
function drush_get_engine($type) {
  return drush_get_context($type . '_engine', FALSE);
}

/**
 * Called by the Drush command (@see _drush_load_command_engines())
 * to cache the active engine instance.
 */
function drush_set_engine($type, $instance) {
  drush_set_context($type . '_engine', $instance);
}

/**
 * Add engine topics to the command topics, if any.
 */
function drush_engine_add_help_topics(&$command) {
  $engine_types = drush_get_engine_types_info();
  foreach ($command['engines'] as $engine_type => $config) {
    $info = $engine_types[$engine_type];
    if (isset($info['topics'])) {
      $command['topics'] = array_merge($command['topics'], $info['topics']);
    }
    if (isset($info['topic'])) {
      $command['topics'][] = $info['topic'];
    }
  }
}