Merge and rename legacy terms based on a mapping on a my_migration.module

merge_ids_during_migration.php

<?php

use Drupal\Core\Database\Database;
use Drupal\migrate\Plugin\MigrationInterface;
use Drupal\migrate\Row;
use Drupal\migrate\Plugin\MigrateSourceInterface;


/**
 * Populate vocab renaming tables from our csv source file with the old name and new name - this 
 * allows us to update the csv and import it before we trigger the migration to keep this mapping
 * fresh
 */
function my_migration_data_import($vocab_name) {
  $file = fopen(drupal_get_path('module', 'my_migration') . "/data/$vocab_name.csv", "r");
  while (!feof($file)) {
    $sections = fgetcsv($file);
    db_insert("my_migration_$vocab_name")
      ->fields([
        'legacy_id' => $sections[0],
        'old_name' => $sections[1],
        'new_name' => $sections[2],
      ])
      ->execute();
  }
  fclose($file);
}

/**
 * Truncate and refresh vocab renaming tables - we trigger this before a migration runs using an Event but it can 
 * be triggered from Drush
 */
function my_migration_refresh_tables() {
  $vocabs = ['section', 'subject'];
  foreach ($vocabs as $vocab => $vocab_name) {
    $db = Database::getConnection('default');
    $table = "my_migration_$vocab_name";
    if ($db->schema()->tableExists($table)) {
      Database::getConnection('default')->truncate($table)->execute();
    }
    my_migration_data_import($vocab_name);
  }
}

/**
 * Look up taxonomy terms by name - this is a helper function that we call 
 * in the my_migration_fetch_term_mapping
 */
function my_migration_get_termid_by_name($name = NULL, $vid = NULL) {
  $properties = [];
  if (!empty($name)) {
    $properties['name'] = $name;
  }
  if (!empty($vid)) {
    $properties['vid'] = $vid;
  }
  $terms = \Drupal::entityManager()
    ->getStorage('taxonomy_term')
    ->loadByProperties($properties);
  $term = reset($terms);
  return !empty($term) ? $term->id() : 0;
}

/**
 * This is the helper function that we call in prepareRow for this migration and it
 * does a lookup based on the D8 database to find the term by the actual string name.
 * It utilizes the function above to find the actual term id which should be in the
 * migreate map table
 */
function my_migration_fetch_term_mapping($row, $table, $row_property) {
  // We are rewriting some legacy term names and skipping specific terms
  $term_name = $row->getSourceProperty($row_property);
  $query = Database::getConnection()
    ->select($table, 'n');
  $query->fields('n', [
    'new_name',
  ]);
  $query->condition('old_name', $term_name);
  $result = $query->execute()->fetchAssoc();
  return $result;
}


/**
 * Implements hook_migrate_MIGRATE_ID_prepare_row()
 *
 * @param \Drupal\migrate\Row $row
 * @param \Drupal\migrate\Plugin\MigrateSourceInterface $source
 * @param \Drupal\migrate\Plugin\MigrationInterface $migration
 */
function my_migration_migrate_subject_prepare_row(Row $row, MigrateSourceInterface $source, MigrationInterface $migration) {
  $id_map = $migration->getIdMap();
  // We are rewriting some legacy term names and skipping specific terms
  $row_property = 'sub_name';
  $term = $row->getSourceProperty($row_property);
  $result = my_migration_fetch_term_mapping($row, 'my_migration_subject', $row_property);
  if (isset($result['new_name'])) {
    // If the new term name is set to 'Delete' - we will skip this term
    if ($result['new_name'] == 'Delete') {
      //skip this row - we don't want this term
      $migration->getIdMap()
        ->saveMessage($row->getSourceIdValues(), "Skipping legacy term:  $term", MigrationInterface::MESSAGE_INFORMATIONAL);
      return FALSE;
    }
    else {
      // If we are not skipping this term, check to see if this term will be merged and set the destination
      // tid to the existing term (merge the legacy terms)
      $existing_tid = my_migration_get_termid_by_name($result['new_name'], 'section');
      if ($existing_tid) {
        $id_map->saveIdMapping($row, [$existing_tid], \Drupal\migrate\Plugin\MigrateIdMapInterface::STATUS_IMPORTED, $rollback_action = \Drupal\migrate\Plugin\MigrateIdMapInterface::ROLLBACK_DELETE);
      }
      else {
        $row->setSourceProperty('sec_name', $result['new_name']);
      }
    }
  }
}