term_merge.module in Term Merge 7

Provide functionality for merging taxonomy terms one into another.

File

term_merge.module

<?php

/**
 * @file
 * Provide functionality for merging taxonomy terms one into another.
 */

/**
 * Constant to use in term merge action.
 *
 * Constant denotes "do not create HTTP redirect" logic for term merge action.
 *
 * @var int
 */
define('TERM_MERGE_NO_REDIRECT', -1);

/**
 * Implements hook_menu().
 */
function term_merge_menu() {
  $items = array();
  $items['admin/structure/taxonomy/%taxonomy_vocabulary_machine_name/merge'] = array(
    'title' => 'Merge terms',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'term_merge_form',
      3,
    ),
    'access callback' => 'term_merge_access',
    'access arguments' => array(
      3,
    ),
    'file' => 'term_merge.pages.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/structure/taxonomy/%taxonomy_vocabulary_machine_name/merge/default'] = array(
    'title' => 'Default',
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/structure/taxonomy/%taxonomy_vocabulary_machine_name/merge/duplicates'] = array(
    'title' => 'Merge Duplicate Terms',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'term_merge_duplicates_form',
      3,
    ),
    'access callback' => 'term_merge_access',
    'access arguments' => array(
      3,
    ),
    'file' => 'term_merge.pages.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['taxonomy/term/%taxonomy_term/merge'] = array(
    'title' => 'Merge Terms',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'term_merge_form',
      NULL,
      2,
    ),
    'access callback' => 'term_merge_access',
    'access arguments' => array(
      NULL,
      2,
    ),
    'file' => 'term_merge.pages.inc',
    'type' => MENU_LOCAL_TASK,
    'weight' => 10,
  );
  $items['taxonomy/term/%taxonomy_term/merge/default'] = array(
    'title' => 'Default',
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['taxonomy/term/%taxonomy_term/merge/duplicates'] = array(
    'title' => 'Merge Duplicate Terms',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'term_merge_duplicates_form',
      NULL,
      2,
    ),
    'access callback' => 'term_merge_access',
    'access arguments' => array(
      NULL,
      2,
    ),
    'file' => 'term_merge.pages.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['term-merge/autocomplete/term-trunk/%taxonomy_vocabulary_machine_name'] = array(
    'title' => 'Autocomplete Term Merge form term trunk',
    'page callback' => 'term_merge_form_term_trunk_widget_autocomplete_autocomplete',
    'page arguments' => array(
      3,
    ),
    'access callback' => 'term_merge_access',
    'access arguments' => array(
      3,
    ),
    'file' => 'term_merge.pages.inc',
    'type' => MENU_CALLBACK,
  );
  $items['admin/config/user-interface/term-merge'] = array(
    'title' => 'Term Merge settings',
    'description' => 'Configure Term Merge module.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'term_merge_admin_settings_form',
    ),
    'access arguments' => array(
      'administer term merge',
    ),
    'file' => 'term_merge.admin.inc',
  );
  return $items;
}

/**
 * Implements hook_admin_paths().
 */
function term_merge_admin_paths() {
  return array(
    'taxonomy/term/*/merge' => TRUE,
    'taxonomy/term/*/merge/*' => TRUE,
  );
}

/**
 * Implements hook_permission().
 */
function term_merge_permission() {
  $permissions = array();
  $permissions['administer term merge'] = array(
    'title' => t('Administer Term merge'),
    'description' => t('Administer settings of the Term merge module.'),
  );
  $permissions['merge terms'] = array(
    'title' => t('Merge any terms'),
    'description' => t('Gives the ability to merge any taxonomy terms.'),
  );
  $vocabularies = taxonomy_get_vocabularies();
  foreach ($vocabularies as $vocabulary) {
    $permissions['merge ' . $vocabulary->machine_name . ' terms'] = array(
      'title' => t('Merge %name vocabulary terms', array(
        '%name' => $vocabulary->name,
      )),
      'description' => t('Gives the ability to merge taxonomy terms that belong to vocabulary %name.', array(
        '%name' => $vocabulary->name,
      )),
    );
  }
  return $permissions;
}

/**
 * Implements hook_action_info().
 */
function term_merge_action_info() {
  return array(
    'term_merge_action' => array(
      'type' => 'taxonomy_term',
      'label' => t('Merge term'),
      'configurable' => TRUE,
      'behavior' => array(
        'view_property',
      ),
      'pass rows' => TRUE,
    ),
  );
}

/**
 * Implements hook_help().
 */
function term_merge_help($path, $arg) {
  switch ($path) {

    // Main module help for the Term Merge module.
    case 'admin/help#term_merge':
      return '<p>' . t('Allows you to merge multiple terms into one and and at the same time update all fields referencing the old ones.') . '</p>';
      break;
  }
}

/**
 * Implements hook_ctools_plugin_type().
 */
function term_merge_ctools_plugin_type() {
  $plugins = array();
  $plugins['duplicate_suggestion'] = array(
    'defaults' => array(
      'title' => NULL,
      'description' => NULL,
      'hash callback' => NULL,
      'weight' => 0,
    ),
  );
  return $plugins;
}

/**
 * Implements hook_ctools_plugin_directory().
 */
function term_merge_ctools_plugin_directory($owner, $plugin_type) {
  switch ($owner) {
    case 'term_merge':
      switch ($plugin_type) {
        case 'duplicate_suggestion':
          return 'plugins/' . $plugin_type;
      }
      break;
    case 'synonyms':
      switch ($plugin_type) {
        case 'behavior':
          return 'plugins/' . $plugin_type;
      }
      break;
  }
}

/**
 * Implements hook_synonyms_provider_field_behavior_implementation_info().
 */
function term_merge_synonyms_provider_field_behavior_implementation_info($behavior) {
  switch ($behavior) {
    case 'term_merge':
      return array(
        'number_integer' => 'TextTermMergeSynonymsBehavior',
        'number_decimal' => 'TextTermMergeSynonymsBehavior',
        'number_float' => 'TextTermMergeSynonymsBehavior',
        'text' => 'TextTermMergeSynonymsBehavior',
        'taxonomy_term_reference' => 'TaxonomyTermMergeSynonymsBehavior',
        'entityreference' => 'EntityReferenceTermMergeSynonymsBehavior',
      );
      break;
  }
  return array();
}

/**
 * Access callback for term merge action.
 *
 * Decide whether to grant access to an account for an operation of merging
 * terms in a vocabulary.
 *
 * @param object $vocabulary
 *   Fully loaded vocabulary object inside of which term merge operation is
 *   requested for access granting
 * @param object $term
 *   Fully loaded term object which belongs to the vocabulary inside of which
 *   term merge operation is requested for access granting. You are supposed
 *   only to provide either $vocabulary or $term. Depending on your context it
 *   might be more convenient for you to provide $term, and on other occasions
 *   it might be $vocabulary of more convenience
 * @param object $account
 *   Fully loaded user object who is requesting access granting for the
 *   operation of term merging. You may provide nothing here, and the currently
 *   logged in user will be considered
 *
 * @return bool
 *   Whether the access for term merging operation has been granted
 */
function term_merge_access($vocabulary = NULL, $term = NULL, $account = NULL) {
  if (is_null($vocabulary) && is_null($term)) {

    // This is no go, at least one of these 2 has to be provided.
    return FALSE;
  }
  if (is_null($account)) {

    // Falling back on currently logged in user.
    $account = $GLOBALS['user'];
  }
  if (is_null($vocabulary)) {
    $vocabulary = taxonomy_vocabulary_load($term->vid);
  }
  return user_access('merge terms', $account) || user_access('merge ' . $vocabulary->machine_name . ' terms', $account);
}

/**
 * Generate the configuration form for action "Term merge".
 */
function term_merge_action_form($context, &$form_state) {
  $term_branch_value = isset($form_state['selection']) && is_array($form_state['selection']) ? $form_state['selection'] : array();
  $vocabulary = FALSE;
  if (!empty($term_branch_value)) {
    $vocabulary = db_select('taxonomy_term_data', 't')
      ->fields('t', array(
      'vid',
    ))
      ->condition('tid', reset($term_branch_value))
      ->execute()
      ->fetchField();
    $vocabulary = taxonomy_vocabulary_load($vocabulary);
  }
  if ($vocabulary) {
    $form = array();
    module_load_include('inc', 'term_merge', 'term_merge.pages');
    term_merge_form_base($form, $form_state, $vocabulary, $term_branch_value);

    // The "step" merge parameter does not make sense here, since the batch will
    // be invoked out of Term Merge scope.
    $form['step']['#access'] = FALSE;
  }
  else {
    $form['vocabulary_missing'] = array(
      '#markup' => '<b>' . t('Oops, something did not seem to go right. Term merge module cannot determine within which vocabulary merge is about to happen. You might want to report it to the <a href="@url">Term Merge issue queue</a>.', array(
        '@url' => 'https://www.drupal.org/project/issues/term_merge',
      )) . '</b>',
    );
  }
  return $form;
}

/**
 * Form submission function.
 *
 * Store information about configurable action.
 */
function term_merge_action_submit($form, &$form_state) {
  return array(
    'term_trunk' => $form_state['values']['term_trunk']['tid'],
  ) + term_merge_merge_options_submit($form, $form_state, $form);
}

/**
 * Action function. Perform action "Term Merge".
 */
function term_merge_action($object, $context) {
  $term_branch = $object;
  $term_trunk = taxonomy_term_load($context['term_trunk']);
  $vocabulary = taxonomy_vocabulary_load($term_branch->vid);
  $term_branch_children = array();
  foreach (taxonomy_get_tree($term_branch->vid, $term_branch->tid) as $term) {
    $term_branch_children[] = $term->tid;
  }
  if ($term_branch->vid != $term_trunk->vid) {
    watchdog('term_merge', 'Trying to merge 2 terms (%term_branch, %term_trunk) from different vocabularies', array(
      '%term_branch' => $term_branch->name,
      '%term_trunk' => $term_trunk->name,
    ), WATCHDOG_WARNING);
    return;
  }
  if ($term_branch->tid == $term_trunk->tid) {
    watchdog('term_merge', 'Trying to merge a term %term into itself.', array(
      '%term' => $term_branch->name,
    ), WATCHDOG_WARNING);
    return;
  }
  if (in_array($term_trunk->tid, $term_branch_children)) {
    watchdog('term_merge', 'Trying to merge a term %term_branch into its child %term_trunk.', array(
      '%term_branch' => $term_branch->name,
      '%term_trunk' => $term_trunk->name,
    ), WATCHDOG_WARNING);
    return;
  }

  // Defining some default values.
  if (!isset($context['term_branch_keep'])) {

    // It's easier to manually delete the unwanted terms, rather than
    // search for your DB back up. So by default we keep the term branch.
    $context['term_branch_keep'] = TRUE;
  }
  if (!isset($context['merge_fields'])) {

    // Initializing it with an empty array if client of this function forgot to
    // provide info about what fields to merge.
    $context['merge_fields'] = array();
  }
  if (!isset($context['keep_only_unique'])) {

    // Seems logical that mostly people will prefer to keep only one value in
    // term reference field per taxonomy term.
    $context['keep_only_unique'] = TRUE;
  }
  if (!isset($context['redirect']) || !module_exists('redirect')) {

    // This behavior requires Redirect module installed and enabled.
    $context['redirect'] = TERM_MERGE_NO_REDIRECT;
  }
  if (!isset($context['synonyms']) || !module_exists('synonyms')) {

    // This behavior requires Synonyms module installed and enabled.
    $context['synonyms'] = NULL;
  }

  // Calling a hook, this way we let whoever else to react and do his own extra
  // logic when merging of terms occurs. We prefer to call it before we handle
  // our own logic, because our logic might delete $term_branch and maybe a
  // module that implements this hook needs this term not deleted yet.
  module_invoke_all('term_merge', $term_trunk, $term_branch, $context);
  if (!empty($context['merge_fields'])) {

    // "Merging" the fields from $term_branch into $term_trunk where it is
    // possible.
    foreach ($context['merge_fields'] as $field_name) {

      // Getting the list of available languages for this field.
      $languages = array();
      if (isset($term_trunk->{$field_name}) && is_array($term_trunk->{$field_name})) {
        $languages = array_merge($languages, array_keys($term_trunk->{$field_name}));
      }
      if (isset($term_branch->{$field_name}) && is_array($term_branch->{$field_name})) {
        $languages = array_merge($languages, array_keys($term_branch->{$field_name}));
      }
      $languages = array_unique($languages);

      // Merging the data of both terms into $term_trunk.
      foreach ($languages as $language) {
        if (!isset($term_trunk->{$field_name}[$language])) {
          $term_trunk->{$field_name}[$language] = array();
        }
        if (!isset($term_branch->{$field_name}[$language])) {
          $term_branch->{$field_name}[$language] = array();
        }
        $items = array_merge($term_trunk->{$field_name}[$language], $term_branch->{$field_name}[$language]);
        $unique_items = array();
        foreach ($items as $item) {
          $unique_items[serialize($item)] = $item;
        }
        $items = array_values($unique_items);
        $term_trunk->{$field_name}[$language] = $items;
      }
    }

    // And now we can save $term_trunk after shifting all the fields from
    // $term_branch.
    taxonomy_term_save($term_trunk);
  }
  $result = array();
  foreach (term_merge_fields_with_foreign_key('taxonomy_term_data', 'tid') as $field) {
    $result[$field['field_name']] = array();
    $query = new EntityFieldQuery();

    // Making sure we search in the entire scope of entities.
    $query
      ->addMetaData('account', user_load(1));
    $query
      ->fieldCondition($field['field_name'], $field['term_merge_field_column'], $term_branch->tid);
    $_result = $query
      ->execute();
    $result[$field['field_name']]['entities'] = $_result;
    $result[$field['field_name']]['column'] = $field['term_merge_field_column'];
  }

  // Now we load all entities that have fields pointing to $term_branch.
  foreach ($result as $field_name => $field_data) {
    $column = $field_data['column'];
    foreach ($field_data['entities'] as $entity_type => $v) {
      $ids = array_keys($v);
      $entities = entity_load($entity_type, $ids);

      // After we have loaded it, we alter the field to point to $term_trunk.
      foreach ($entities as $entity) {

        // What is more, we have to do it for every available language.
        foreach ($entity->{$field_name} as $language => $items) {

          // Keeping track of whether term trunk is already present in this
          // field in this language. This is useful for the option
          // 'keep_only_unique'.
          $is_trunk_added = FALSE;
          foreach ($entity->{$field_name}[$language] as $delta => $item) {
            if ($context['keep_only_unique'] && $is_trunk_added && in_array($item[$column], array(
              $term_trunk->tid,
              $term_branch->tid,
            ))) {

              // We are instructed to keep only unique references and we already
              // have term trunk in this field, so we just unset value for this
              // delta.
              unset($entity->{$field_name}[$language][$delta]);
            }
            else {

              // Merging term references if necessary, and keep an eye on
              // whether we already have term trunk among this field values.
              switch ($item[$column]) {
                case $term_trunk->tid:
                  $is_trunk_added = TRUE;
                  break;
                case $term_branch->tid:
                  $is_trunk_added = TRUE;
                  $entity->{$field_name}[$language][$delta][$column] = $term_trunk->tid;
                  break;
              }
            }
          }

          // Above in the code, while looping through all deltas of this field,
          // we might have unset some of the deltas to keep term references
          // unique. We should better keep deltas as a series of consecutive
          // numbers, because it is what it is supposed to be.
          $entity->{$field_name}[$language] = array_values($entity->{$field_name}[$language]);
        }

        // Integration with workbench_moderation module. Without this code, if
        // we save the node for which workbench moderation is enabled, then
        // it will go from "published" state into "draft". Though in fact we do
        // not change anything in the node and therefore it should persist in
        // published state.
        if (module_exists('workbench_moderation') && $entity_type == 'node') {
          $entity->workbench_moderation['updating_live_revision'] = TRUE;
        }

        // After updating all the references, save the entity.
        entity_save($entity_type, $entity);
      }
    }
  }

  // Adding term branch as synonym (Synonyms module integration).
  if ($context['synonyms']) {
    term_merge_add_entity_as_synonym($term_trunk, 'taxonomy_term', $context['synonyms'], $term_branch, 'taxonomy_term');
  }

  // It turned out we gotta go tricky with the Redirect module. If we create
  // redirection before deleting the branch term (if we are instructed to delete
  // in this action) redirect module will do its "auto-clean up" in
  // hook_entity_delete() and will delete our just created redirects. But at the
  // same time we have to get the path alias of the $term_branch before it gets
  // deleted. Otherwise the path alias will be deleted along with the term
  // itself. Similarly would be lost all redirects pointing to branch term
  // paths. We will redirect normal term path and its RSS feed.
  $redirect_paths = array();
  if ($context['redirect'] != TERM_MERGE_NO_REDIRECT) {
    $redirect_paths['taxonomy/term/' . $term_trunk->tid] = array(
      'taxonomy/term/' . $term_branch->tid,
    );
    $redirect_paths['taxonomy/term/' . $term_trunk->tid . '/feed'] = array(
      'taxonomy/term/' . $term_branch->tid . '/feed',
    );
    foreach ($redirect_paths as $redirect_destination => $redirect_sources) {

      // We create redirect from Drupal normal path, then we try to fetch its
      // alias. Lastly we collect a set of redirects that point to either of the
      // 2 former paths. Everything we were able to fetch will be redirecting to
      // the trunk term.
      $alias = drupal_get_path_alias($redirect_sources[0]);
      if ($alias != $redirect_sources[0]) {
        $redirect_sources[] = $alias;
      }
      $existing_redirects = array();
      foreach ($redirect_sources as $redirect_source) {
        foreach (redirect_load_multiple(array(), array(
          'redirect' => $redirect_source,
        )) as $v) {
          $existing_redirects[] = $v->source;
        }
      }
      $redirect_paths[$redirect_destination] = array_unique(array_merge($redirect_sources, $existing_redirects));
    }
  }
  if (!$context['term_branch_keep']) {

    // If we are going to delete branch term, we need firstly to make sure
    // all its children now have the parent of term_trunk.
    foreach (taxonomy_get_children($term_branch->tid, $vocabulary->vid) as $child) {
      $parents = taxonomy_get_parents($child->tid);

      // Deleting the parental link to the term that is being merged.
      unset($parents[$term_branch->tid]);

      // And putting the parental link to the term that we merge into.
      $parents[$term_trunk->tid] = $term_trunk;
      $parents = array_unique(array_keys($parents));
      $child->parent = $parents;
      taxonomy_term_save($child);
    }

    // Views module integration. We update all Views taxonomy filter handlers
    // configured to filter on term branch to filter on term trunk now, since
    // the former becomes the latter.
    if (module_exists('views')) {
      $views = views_get_all_views();
      foreach ($views as $view) {

        // For better efficiency, we keep track of whether we have updated
        // anything in a view, and thus whether we need to save it.
        $needs_saving = FALSE;

        // Even worse, we have to go through each display of each view.
        foreach ($view->display as $display_id => $display) {
          $view
            ->set_display($display_id);
          $filters = $view->display_handler
            ->get_handlers('filter');
          foreach ($filters as $filter_id => $filter_handler) {

            // Currently we know how to update filters only of this particular
            // class.
            if (get_class($filter_handler) == 'views_handler_filter_term_node_tid') {
              $filter = $view
                ->get_item($display_id, 'filter', $filter_id);
              if (isset($filter['value'][$term_branch->tid])) {

                // Substituting term branch with term trunk.
                unset($filter['value'][$term_branch->tid]);
                $filter['value'][$term_trunk->tid] = $term_trunk->tid;
                $view
                  ->set_item($display_id, 'filter', $filter_id, $filter);
                $needs_saving = TRUE;
              }
            }
          }
        }
        if ($needs_saving) {
          $view
            ->save();
        }
      }
    }

    // We are instructed to delete the term branch after the merge,
    // and so we do.
    taxonomy_term_delete($term_branch->tid);
  }

  // Here we do the 2nd part of integration with the Redirect module. Once the
  // branch term has been deleted (if deleted), we can add the redirects
  // without being afraid that the redirect module will delete them in its
  // hook_entity_delete().
  foreach ($redirect_paths as $redirect_destination => $redirect_sources) {
    foreach ($redirect_sources as $redirect_source) {
      $redirect = redirect_load_by_source($redirect_source);
      if (!$redirect) {

        // Seems like redirect from such URI does not exist yet, we will create
        // it.
        $redirect = new stdClass();
        redirect_object_prepare($redirect, array(
          'source' => $redirect_source,
        ));
      }
      $redirect->redirect = $redirect_destination;
      $redirect->status_code = $context['redirect'];
      redirect_save($redirect);
    }
  }
  watchdog('term_merge', 'Successfully merged term %term_branch into term %term_trunk in vocabulary %vocabulary. Context: @context', array(
    '%term_branch' => $term_branch->name,
    '%term_trunk' => $term_trunk->name,
    '%vocabulary' => $vocabulary->name,
    '@context' => var_export($context, 1),
  ));
}

/**
 * Merge terms one into another using batch API.
 *
 * @param array $term_branch
 *   A single term tid or an array of term tids to be merged, aka term branches
 * @param int $term_trunk
 *   The tid of the term to merge term branches into, aka term trunk
 * @param array $merge_settings
 *   Array of settings that control how merging should happen. Currently
 *   supported settings are:
 *     - term_branch_keep: (bool) Whether the term branches should not be
 *       deleted, also known as "merge only occurrences" option
 *     - merge_fields: (array) Array of field names whose values should be
 *       merged into the values of corresponding fields of term trunk (until
 *       each field's cardinality limit is reached)
 *     - keep_only_unique: (bool) Whether after merging within one field only
 *       unique taxonomy term references should be kept in other entities. If
 *       before merging your entity had 2 values in its taxonomy term reference
 *       field and one was pointing to term branch while another was pointing to
 *       term trunk, after merging you will end up having your entity
 *       referencing to the same term trunk twice. If you pass TRUE in this
 *       parameter, only a single reference will be stored in your entity after
 *       merging
 *     - redirect: (int) HTTP code for redirect from $term_branch to
 *       $term_trunk, 0 stands for the default redirect defined in Redirect
 *       module. Use constant TERM_MERGE_NO_REDIRECT to denote not creating any
 *       HTTP redirect. Note: this parameter requires Redirect module enabled,
 *       otherwise it will be disregarded
 *     - synonyms: (string) Optional field name of trunk term into which branch
 *       terms should be added as synonyms (until field's cardinality limit
 *       is reached). Note: this parameter requires Synonyms module enabled,
 *       otherwise it will be disregarded
 *     - step: (int) How many term branches to merge per script run in batch. If
 *       you are hitting time or memory limits, decrease this parameter
 */
function term_merge($term_branch, $term_trunk, $merge_settings = array()) {

  // Older versions of this module had another interface of this function,
  // as backward capability we still support the older interface, instead of
  // supplying a $merge_settings array, it was supplying all the settings as
  // additional function arguments.
  // @todo: delete this backward capability at some point.
  if (!is_array($merge_settings)) {
    $merge_settings = array(
      'term_branch_keep' => $merge_settings,
    );
  }

  // Create an array of sources if it isn't yet.
  if (!is_array($term_branch)) {
    $term_branch = array(
      $term_branch,
    );
  }

  // Creating a skeleton for the merging batch.
  $batch = array(
    'title' => t('Merging terms'),
    'operations' => array(
      array(
        '_term_merge_batch_process',
        array(
          $term_branch,
          $term_trunk,
          $merge_settings,
        ),
      ),
    ),
    'finished' => 'term_merge_batch_finished',
    'file' => drupal_get_path('module', 'term_merge') . '/term_merge.batch.inc',
  );

  // Initialize the batch process.
  batch_set($batch);
}

/**
 * Retrieve information about ctools plugin of type 'duplicate suggestion'.
 *
 * @param string $id
 *   Supply here ID of the cTool plugin information about which you want to
 *   retrieve. You may omit this argument and then information on all duplicate
 *   suggestion plugins will be returned
 *
 * @return array
 *   Array of information on all available duplicate suggestion plugins or if
 *   $id was provided, then information on that plugin
 */
function term_merge_duplicate_suggestion($id = NULL) {
  ctools_include('plugins');
  $plugins = ctools_get_plugins('term_merge', 'duplicate_suggestion', $id);
  if (!$id) {

    // Sort the list of plugins by their weight.
    uasort($plugins, 'drupal_sort_weight');
  }
  return $plugins;
}

/**
 * Generate and return form elements that control behavior of merge action.
 *
 * Output of this function should be used in any form that merges terms,
 * ensuring unified interface. It should be used in conjunction with
 * term_merge_merge_options_submit(), which will process the submitted values
 * for you and return an array of merge settings.
 *
 * @param object $vocabulary
 *   Fully loaded taxonomy vocabulary object in which merging occurs
 *
 * @return array
 *   Array of form elements that allow controlling term merge action
 *
 * @see term_merge_merge_options_submit()
 */
function term_merge_merge_options_elements($vocabulary) {

  // @todo: it would be nice to provide some ability to supply default values
  // for each setting.
  $form = array();

  // Getting bundle name and a list of fields attached to this bundle for
  // further use down below in the code while generating form elements.
  $bundle = field_extract_bundle('taxonomy_term', $vocabulary);
  $instances = field_info_instances('taxonomy_term', $bundle);
  $form['term_branch_keep'] = array(
    '#type' => 'checkbox',
    '#title' => t('Only merge occurrences'),
    '#description' => t('Check this if you want to only merge the occurrences of the specified terms, i.e. the terms will not be deleted from your vocabulary.'),
  );
  if (!empty($instances)) {
    $options = array();
    foreach ($instances as $instance) {
      $options[$instance['field_name']] = $instance['label'];
    }
    $form['merge_fields'] = array(
      '#type' => 'checkboxes',
      '#title' => t('Merge Term Fields'),
      '#description' => t('Check the fields whose values from branch terms you want to add to the values of corresponding fields of the trunk term. <b>Important note:</b> the values will be added until the cardinality limit for the selected fields is reached and only unique values for each field will be saved.'),
      '#options' => $options,
    );
  }
  $form['keep_only_unique'] = array(
    '#type' => 'checkbox',
    '#title' => t('Keep only unique terms after merging'),
    '#description' => t('Sometimes after merging you may end up having a node (or any other entity) pointing twice to the same taxonomy term, tick this checkbox if want to keep only unique terms in other entities after merging.'),
    '#default_value' => TRUE,
  );
  if (module_exists('redirect')) {
    $form['redirect'] = array(
      // We respect access rights defined in redirect.module here.
      '#access' => user_access('administer redirects'),
      '#type' => 'select',
      '#title' => t('Create Redirect'),
      '#description' => t('If you want to create an HTTP redirect from your branch terms to the trunk term, please, choose the HTTP redirect code here.'),
      '#required' => TRUE,
      '#options' => term_merge_redirect_options(),
      '#default_value' => variable_get('term_merge_default_redirect', TERM_MERGE_NO_REDIRECT),
    );
  }
  else {
    $form['redirect'] = array(
      '#markup' => t('Enable the module ' . l('Redirect', 'http://drupal.org/project/redirect') . ' if you want to do an HTTP redirect from your term branch to the term trunk.'),
    );
  }
  if (module_exists('synonyms')) {
    $options = array(
      '' => t('None'),
    );
    if (function_exists('synonyms_behavior_get')) {

      // We are in Synonyms 7.x-1.5 and above.
      foreach (synonyms_behavior_get('term_merge', 'taxonomy_term', $vocabulary->machine_name, TRUE) as $behavior_implementation) {
        $options[$behavior_implementation['provider']] = $behavior_implementation['label'];
      }
    }
    else {

      // This is how we used to retrieve possible synonyms field prior to
      // Synonyms 7.x-1.5. TODO: this should be removed at some point.
      foreach (synonyms_synonyms_fields($vocabulary) as $field_name) {
        $options[$field_name] = $instances[$field_name]['label'];
      }
    }
    $form['synonyms'] = array(
      '#type' => 'radios',
      '#title' => t('Add as Synonyms'),
      '#description' => t('Synonyms module allows you to add branch terms as synonyms into any of fields, enabled as sources of synonyms in vocabulary. Check the field into which you would like to add branch terms as synonym. <b>Important note:</b> the values will be added until the cardinality limit for the selected field is reached.'),
      '#options' => $options,
      '#default_value' => '',
    );
  }
  else {
    $form['synonyms'] = array(
      '#markup' => t('Enable the module ' . l('Synonyms', 'http://drupal.org/project/synonyms') . ' if you want to be able to add branch terms as synonyms into a field of your trunk term.'),
    );
  }
  $form['step'] = array(
    '#type' => 'textfield',
    '#title' => t('Step'),
    '#description' => t('Please, specify how many terms to process per script run in batch. If you are hitting time or memory limits in your PHP, decrease this number.'),
    '#default_value' => 40,
    '#required' => TRUE,
    '#element_validate' => array(
      'element_validate_integer_positive',
    ),
  );
  return $form;
}

/**
 * Return merge settings array.
 *
 * Output of this function should be used for supplying into term_merge()
 * function or for triggering actions_do('term_merge_action', ...) action. This
 * function should be invoked in a form submit handler for a form that used
 * term_merge_merge_options_elements() for generating merge settings elements.
 * It will process data and return an array of merge settings, according to the
 * data user has submitted in your form.
 *
 * @param array $merge_settings_element
 *   That part of form that was generated by term_merge_merge_options_elements()
 * @param array $form_state
 *   Form state array of the submitted form
 * @param array $form
 *   Form array of the submitted form
 *
 * @return array
 *   Array of merge settings that can be used for calling term_merge() or
 *   invoking 'term_merge_action' action
 *
 * @see term_merge_merge_options_elements()
 */
function term_merge_merge_options_submit($merge_settings_element, &$form_state, $form) {
  $merge_settings = array(
    'term_branch_keep' => (bool) $merge_settings_element['term_branch_keep']['#value'],
    'merge_fields' => isset($merge_settings_element['merge_fields']['#value']) ? array_values(array_filter($merge_settings_element['merge_fields']['#value'])) : array(),
    'keep_only_unique' => (bool) $merge_settings_element['keep_only_unique']['#value'],
    'redirect' => isset($merge_settings_element['redirect']['#value']) ? $merge_settings_element['redirect']['#value'] : TERM_MERGE_NO_REDIRECT,
    'synonyms' => isset($merge_settings_element['synonyms']['#value']) ? $merge_settings_element['synonyms']['#value'] : NULL,
    'step' => (int) $merge_settings_element['step']['#value'],
  );
  return $merge_settings;
}

/**
 * Fetch all fields that have a foreign key to provided column.
 *
 * @param string $foreign_table
 *   Name of the table for which to look among foreign keys of all the fields
 * @param string $foreign_column
 *   Name of the column for which to look among foreign keys of all the fields
 *
 * @return array
 *   Array of all fields that have the specified table and column within their
 *   foreign keys. Each of the fields array will be extended to include the
 *   following additional keys:
 *   - term_merge_field_column: (string) Name of the field column that holds
 *     foreign key to the provided table and column
 */
function term_merge_fields_with_foreign_key($foreign_table, $foreign_column) {
  $fields = field_info_fields();
  $result = array();
  foreach ($fields as $field_name => $field_info) {
    foreach ($field_info['foreign keys'] as $foreign_key) {
      if ($foreign_key['table'] == $foreign_table) {
        $column = array_search($foreign_column, $foreign_key['columns']);
        if ($column) {
          $field_info['term_merge_field_column'] = $column;
          $result[] = $field_info;
        }
      }
    }
  }
  return $result;
}

/**
 * Allow to merge $synonym_entity as a synonym into $trunk_entity.
 *
 * Helpful function during various merging operations. It allows you to add a
 * synonym (where possible) into one entity, which will represent another entity
 * in the format expected by the field in which the synonym is being added.
 *
 * @param object $trunk_entity
 *   Fully loaded entity object in which the synonym is being added
 * @param string $trunk_entity_type
 *   Entity type of $trunk_entity
 * @param string $behavior_provider
 *   Machine name of behavior implementation into which the synonym entity
 *   should be merged
 * @param object $synonym_entity
 *   Fully loaded entity object which will be added as a synonym
 * @param string $synonym_entity_type
 *   Entity type of $synonym_entity
 *
 * @return bool
 *   Whether synonym has been successfully added
 */
function term_merge_add_entity_as_synonym($trunk_entity, $trunk_entity_type, $behavior_provider, $synonym_entity, $synonym_entity_type) {
  if ($trunk_entity_type != 'taxonomy_term') {

    // So far we only work with taxonomy terms.
    return FALSE;
  }
  $bundle = entity_extract_ids($trunk_entity_type, $trunk_entity);
  $bundle = $bundle[2];
  $behavior_implementations = synonyms_behavior_get_all_enabled($trunk_entity_type, $bundle, $behavior_provider);
  foreach ($behavior_implementations as $behavior_implementation) {
    if ($behavior_implementation['behavior'] == 'term_merge') {
      $behavior_implementation['object']
        ->mergeTerm($trunk_entity, $synonym_entity, $synonym_entity_type);
      taxonomy_term_save($trunk_entity);
      return TRUE;
    }
  }
  return FALSE;
}

/**
 * Form API element validate function.
 *
 * Make sure term trunk is not among the selected term branches or their
 * children.
 */
function term_merge_form_base_term_trunk_validate($element, &$form_state, $form) {
  $prohibited_trunks = array();
  foreach ($form['#term_merge_term_branch'] as $term_branch) {
    $children = taxonomy_get_tree($form['#vocabulary']->vid, $term_branch);
    $prohibited_trunks[] = $term_branch;
    foreach ($children as $child) {
      $prohibited_trunks[] = $child->tid;
    }
  }
  $value = drupal_array_get_nested_value($form_state['values'], $element['#parents']);
  if (in_array($value['tid'], $prohibited_trunks)) {
    form_error($element['tid'], t('Trunk term cannot be one of the selected branch terms or their children.'));
  }
}

/**
 * Supportive function.
 *
 * Generate form elements for select widget for term trunk element of the term
 * merge form.
 *
 * @param object $vocabulary
 *   Fully loaded taxonomy vocabulary object
 * @param array $term_branch_value
 *   Array of Taxonomy term IDs that are nominated as branch terms.
 */
function term_merge_form_term_trunk_widget_select(&$form, &$form_state, $vocabulary, $term_branch_value) {
  $tree = taxonomy_get_tree($vocabulary->vid);
  $options = array();
  foreach ($tree as $v) {
    $options[$v->tid] = str_repeat('-', $v->depth) . $v->name . ' [tid: ' . $v->tid . ']';
  }
  if (!empty($term_branch_value)) {

    // We have to make sure among term_trunk there is no term_branch or any of
    // their children.
    foreach ($term_branch_value as $v) {
      unset($options[$v]);
      foreach (taxonomy_get_tree($vocabulary->vid, $v) as $child) {
        unset($options[$child->tid]);
      }
    }
  }
  else {

    // Term branch has not been selected yet.
    $options = array();
  }
  $form['term_trunk']['tid'] = array(
    '#type' => 'select',
    '#required' => TRUE,
    '#description' => t('Choose into what term you want to merge.'),
    '#options' => $options,
  );
}

/**
 * Supportive function.
 *
 * Generate form element for hierarchical select widget for term trunk element
 * of the term merge form.
 *
 * @param object $vocabulary
 *   Fully loaded taxonomy vocabulary object
 * @param array $term_branch_value
 *   Array of Taxonomy term IDs that are nominated as branch terms.
 */
function term_merge_form_term_trunk_widget_hs_taxonomy(&$form, &$form_state, $vocabulary, $term_branch_value) {
  $form['term_trunk']['tid'] = array(
    '#type' => 'hierarchical_select',
    '#description' => t('Please select a term to merge into.'),
    '#required' => TRUE,
    '#element_validate' => array(
      'term_merge_form_trunk_term_widget_hs_taxonomy_validate',
    ),
    '#config' => array(
      'module' => 'hs_taxonomy',
      'params' => array(
        'vid' => $vocabulary->vid,
        'exclude_tid' => NULL,
        'root_term' => FALSE,
      ),
      'enforce_deepest' => 0,
      'entity_count' => 0,
      'require_entity' => 0,
      'save_lineage' => 0,
      'level_labels' => array(
        'status' => 0,
      ),
      'dropbox' => array(
        'status' => 0,
      ),
      'editability' => array(
        'status' => 0,
      ),
      'resizable' => TRUE,
      'render_flat_select' => 0,
    ),
  );
}

/**
 * Supportive function.
 *
 * Generate form elements for autocomplete widget for term trunk element of the
 * term merge form.
 *
 * @param object $vocabulary
 *   Fully loaded taxonomy vocabulary object
 * @param array $term_branch_value
 *   Array of Taxonomy term IDs that are nominated as branch terms.
 */
function term_merge_form_term_trunk_widget_autocomplete(&$form, &$form_state, $vocabulary, $term_branch_value) {
  $form['term_trunk']['tid'] = array(
    '#type' => 'textfield',
    '#description' => t("Start typing in a term's name in order to get some suggestions."),
    '#required' => TRUE,
    '#autocomplete_path' => 'term-merge/autocomplete/term-trunk/' . $vocabulary->machine_name,
    '#element_validate' => array(
      'term_merge_form_trunk_term_widget_autocomplete_validate',
    ),
  );
}

/**
 * Supportive function.
 *
 * Validate form element of the autocomplete widget of term trunk element of the
 * term merge form. Make sure the entered string is a name of one of the
 * existing terms in the vocabulary where the merge occurs. If term is found the
 * function substitutes the name with its {taxonomy_term_data}.tid as it is what
 * is expected from a term trunk widget to provide in its value.
 */
function term_merge_form_trunk_term_widget_autocomplete_validate($element, &$form_state, $form) {

  // Field value is "name (tid)", match the tid from parenthesis.
  if (preg_match("/.+\\((\\d+)\\)\$/", $element['#value'], $matches)) {
    $term = taxonomy_term_load($matches[1]);
  }
  else {

    // Assume that the user didn't use the autocomplete but filled in a tid
    // manually.
    $term = taxonomy_get_term_by_name($element['#value'], $form['#vocabulary']->machine_name);
    $term = reset($term);
  }
  if (empty($term)) {

    // Seems like the user has entered a non existing name or tid in the
    // autocomplete textfield.
    form_error($element, t('There are no terms matching %value in the %vocabulary vocabulary.', array(
      '%value' => $element['#value'],
      '%vocabulary' => $form['#vocabulary']->name,
    )));
  }
  else {

    // We have to substitute the field value the term tid in order to make this
    // widget consistent with the interface.
    form_set_value($element, $term->tid, $form_state);
  }
}

/**
 * Supportive function.
 *
 * Validate form element of the Hierarchical Select widget of term trunk element
 * of the term merge form. Convert the value from array to a single tid integer
 * value.
 */
function term_merge_form_trunk_term_widget_hs_taxonomy_validate($element, &$form_state, $form) {
  $tid = 0;
  if (is_array($element['#value']) && !empty($element['#value'])) {
    $tid = (int) array_pop($element['#value']);
  }
  form_set_value($element, $tid, $form_state);
}

/**
 * Retrieve options for possible redirect actions.
 *
 * @return array
 *   Array of options that represent possible redirect actions.
 */
function term_merge_redirect_options() {
  return array(
    TERM_MERGE_NO_REDIRECT => t('No redirect'),
    0 => t('Default (@default)', array(
      '@default' => variable_get('redirect_default_status_code', 301),
    )),
  ) + redirect_status_code_options();
}

Functions

Name	Description
term_merge	Merge terms one into another using batch API.
term_merge_access	Access callback for term merge action.
term_merge_action	Action function. Perform action "Term Merge".
term_merge_action_form	Generate the configuration form for action "Term merge".
term_merge_action_info	Implements hook_action_info().
term_merge_action_submit	Form submission function.
term_merge_add_entity_as_synonym	Allow to merge $synonym_entity as a synonym into $trunk_entity.
term_merge_admin_paths	Implements hook_admin_paths().
term_merge_ctools_plugin_directory	Implements hook_ctools_plugin_directory().
term_merge_ctools_plugin_type	Implements hook_ctools_plugin_type().
term_merge_duplicate_suggestion	Retrieve information about ctools plugin of type 'duplicate suggestion'.
term_merge_fields_with_foreign_key	Fetch all fields that have a foreign key to provided column.
term_merge_form_base_term_trunk_validate	Form API element validate function.
term_merge_form_term_trunk_widget_autocomplete	Supportive function.
term_merge_form_term_trunk_widget_hs_taxonomy	Supportive function.
term_merge_form_term_trunk_widget_select	Supportive function.
term_merge_form_trunk_term_widget_autocomplete_validate	Supportive function.
term_merge_form_trunk_term_widget_hs_taxonomy_validate	Supportive function.
term_merge_help	Implements hook_help().
term_merge_menu	Implements hook_menu().
term_merge_merge_options_elements	Generate and return form elements that control behavior of merge action.
term_merge_merge_options_submit	Return merge settings array.
term_merge_permission	Implements hook_permission().
term_merge_redirect_options	Retrieve options for possible redirect actions.
term_merge_synonyms_provider_field_behavior_implementation_info	Implements hook_synonyms_provider_field_behavior_implementation_info().

Constants

Name	Description
TERM_MERGE_NO_REDIRECT	Constant to use in term merge action.