Issue #2845486 by Jo Fitzgerald, quietone, gaurav.kapoor, ohthehugemanatee,...

Issue #2845486 by Jo Fitzgerald, quietone, gaurav.kapoor, ohthehugemanatee, heddn, Yogesh Pawar, catch, shabana.navas, phenaproxima, mikeryan: Rename Migration process plugin and add documentation

core/modules/aggregator/migration_templates/d6_aggregator_item.yml

@@ -7,7 +7,7 @@ source:
 process:
   iid: iid
   fid:
-    plugin: migration
+    plugin: migration_lookup
     migration: d6_aggregator_feed
     source: fid
   title: title

core/modules/aggregator/migration_templates/d7_aggregator_item.yml

@@ -7,7 +7,7 @@ source:
 process:
   iid: iid
   fid:
-    plugin: migration
+    plugin: migration_lookup
     migration: d7_aggregator_feed
     source: fid
   title: title

core/modules/block_content/migration_templates/d6_custom_block.yml

@@ -8,7 +8,7 @@ process:
   id: bid
   info: info
   'body/format':
-    plugin: migration
+    plugin: migration_lookup
     migration: d6_filter_format
     source: format
   'body/value': body

core/modules/block_content/migration_templates/d7_custom_block.yml

@@ -8,7 +8,7 @@ process:
   id: bid
   info: info
   'body/format':
-    plugin: migration
+    plugin: migration_lookup
     migration: d7_filter_format
     source: format
   'body/value': body

core/modules/book/migration_templates/d6_book.yml

@@ -14,7 +14,7 @@ process:
       method: process
       source: plid
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_book
 destination:
   plugin: book

core/modules/comment/migration_templates/d6_comment.yml

@@ -11,7 +11,7 @@ process:
   # the cid field to allow incremental migrations.
   cid: cid
   pid:
-    plugin: migration
+    plugin: migration_lookup
     migration: d6_comment
     source: pid
   entity_id: nid
@@ -32,7 +32,7 @@ process:
   thread: thread
   'comment_body/value': comment
   'comment_body/format':
-    plugin: migration
+    plugin: migration_lookup
     migration: d6_filter_format
     source: format
 destination:

core/modules/comment/migration_templates/d7_comment.yml

@@ -11,7 +11,7 @@ process:
   # the cid field to allow incremental migrations.
   cid: cid
   pid:
-    plugin: migration
+    plugin: migration_lookup
     migration: d7_comment
     source: pid
   entity_id: nid

core/modules/contact/migration_templates/d6_contact_settings.yml

@@ -11,7 +11,7 @@ process:
   user_default_enabled: contact_default_status
   'flood/limit': contact_hourly_threshold
   default_form:
-    plugin: migration
+    plugin: migration_lookup
     migration: contact_category
     source: default_category
 destination:

core/modules/contact/migration_templates/d7_contact_settings.yml

@@ -11,7 +11,7 @@ process:
   user_default_enabled: contact_default_status
   'flood/limit': contact_threshold_limit
   default_form:
-    plugin: migration
+    plugin: migration_lookup
     migration: contact_category
     source: default_category
 destination:

core/modules/field/migration_templates/d6_field_formatter_settings.yml

@@ -15,7 +15,7 @@ process:
   # field migration.
   field_type_exists:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_field
       source:
         - field_name
@@ -29,7 +29,7 @@ process:
   entity_type: 'constants/entity_type'
   bundle:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_node_type
       source: type_name
     -
@@ -37,7 +37,7 @@ process:
       method: row
   view_mode:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_view_modes
       source:
         - view_mode

core/modules/field/migration_templates/d6_field_instance.yml

@@ -14,7 +14,7 @@ process:
   # field migration.
   field_type_exists:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_field
       source:
         - field_name
@@ -29,7 +29,7 @@ process:
   field_name: field_name
   bundle:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_node_type
       source: type_name
     -

core/modules/field/migration_templates/d6_field_instance_widget_settings.yml

@@ -16,7 +16,7 @@ process:
   # field migration.
   field_type_exists:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_field
       source:
         - field_name
@@ -29,7 +29,7 @@ process:
       method: row
   bundle:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_node_type
       source: type_name
     -

core/modules/field/migration_templates/d7_field_formatter_settings.yml

@@ -13,7 +13,7 @@ process:
   # field migration.
   field_type_exists:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d7_field
       source:
         - field_name
@@ -29,7 +29,7 @@ process:
   bundle: bundle
   view_mode:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d7_view_modes
       source:
         - entity_type

core/modules/field/migration_templates/d7_field_instance_widget_settings.yml

@@ -14,7 +14,7 @@ process:
   # field migration.
   field_type_exists:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d7_field
       source:
         - field_name

core/modules/file/migration_templates/d6_upload.yml

@@ -13,7 +13,7 @@ process:
     source: upload
     process:
       target_id:
-        plugin: migration
+        plugin: migration_lookup
         migration: d6_file
         source: fid
       display: list

core/modules/file/migration_templates/d6_upload_field_instance.yml

@@ -13,7 +13,7 @@ process:
   entity_type: 'constants/entity_type'
   bundle:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d6_node_type
       source: node_type
     -

core/modules/forum/migration_templates/d6_forum_settings.yml

@@ -18,7 +18,7 @@ process:
   'topics/page_limit': forum_per_page
   'topics/order': forum_order
   vocabulary:
-    plugin: migration
+    plugin: migration_lookup
     migration: d6_taxonomy_vocabulary
     source: forum_nav_vocabulary
 destination:

core/modules/forum/migration_templates/d7_forum_settings.yml

@@ -18,7 +18,7 @@ process:
   'topics/page_limit': forum_per_page
   'topics/order': forum_order
   vocabulary:
-    plugin: migration
+    plugin: migration_lookup
     migration: d7_taxonomy_vocabulary
     source: forum_nav_vocabulary
 destination:

core/modules/menu_link_content/migration_templates/d6_menu_links.yml

@@ -10,7 +10,7 @@ process:
   description: description
   menu_name:
     -
-      plugin: migration
+      plugin: migration_lookup
       # The menu migration is in the system module.
       migration: d6_menu
       source: menu_name

core/modules/menu_link_content/migration_templates/d7_menu_links.yml

@@ -13,7 +13,7 @@ process:
   description: description
   menu_name:
     -
-      plugin: migration
+      plugin: migration_lookup
       migration: d7_menu
       source: menu_name
     -

core/modules/migrate/src/Plugin/migrate/process/DefaultValue.php

@@ -27,7 +27,7 @@
  * process:
  *   uid:
  *     -
- *       plugin: migration
+ *       plugin: migration_lookup
  *       migration: users
  *       source: author
  *     -

core/modules/migrate/src/Plugin/migrate/process/Migration.php

@@ -2,16 +2,8 @@
 
 namespace Drupal\migrate\Plugin\migrate\process;
 
-use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
-use Drupal\migrate\MigrateSkipProcessException;
-use Drupal\migrate\Plugin\MigratePluginManagerInterface;
-use Drupal\migrate\Plugin\MigrationPluginManagerInterface;
-use Drupal\migrate\Plugin\MigrateIdMapInterface;
-use Drupal\migrate\ProcessPluginBase;
-use Drupal\migrate\Plugin\MigrationInterface;
-use Drupal\migrate\MigrateExecutableInterface;
-use Drupal\migrate\Row;
-use Symfony\Component\DependencyInjection\ContainerInterface;
+@trigger_error('The ' . __NAMESPACE__ . '\Migration is deprecated in
+Drupal 8.4.0 and will be removed before Drupal 9.0.0. Instead, use ' . __NAMESPACE__ . '\MigrationLookup', E_USER_DEPRECATED);
 
 /**
  * Calculates the value of a property based on a previous migration.
@@ -21,156 +13,8 @@
  * @MigrateProcessPlugin(
  *   id = "migration"
  * )
+ *
+ * @deprecated in Drupal 8.3.x and will be removed in Drupal 9.0.x.
+ *  Use \Drupal\migrate\Plugin\migrate\process\MigrationLookup instead.
  */
-class Migration extends ProcessPluginBase implements ContainerFactoryPluginInterface {
-
-  /**
-   * The process plugin manager.
-   *
-   * @var \Drupal\migrate\Plugin\MigratePluginManager
-   */
-  protected $processPluginManager;
-
-  /**
-   * The migration plugin manager.
-   *
-   * @var \Drupal\migrate\Plugin\MigrationPluginManagerInterface
-   */
-  protected $migrationPluginManager;
-
-  /**
-   * The migration to be executed.
-   *
-   * @var \Drupal\migrate\Plugin\MigrationInterface
-   */
-  protected $migration;
-
-  /**
-   * {@inheritdoc}
-   */
-  public function __construct(array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration, MigrationPluginManagerInterface $migration_plugin_manager, MigratePluginManagerInterface $process_plugin_manager) {
-    parent::__construct($configuration, $plugin_id, $plugin_definition);
-    $this->migrationPluginManager = $migration_plugin_manager;
-    $this->migration = $migration;
-    $this->processPluginManager = $process_plugin_manager;
-  }
-
-  /**
-   * {@inheritdoc}
-   */
-  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration = NULL) {
-    return new static(
-      $configuration,
-      $plugin_id,
-      $plugin_definition,
-      $migration,
-      $container->get('plugin.manager.migration'),
-      $container->get('plugin.manager.migrate.process')
-    );
-  }
-
-  /**
-   * {@inheritdoc}
-   */
-  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
-    $migration_ids = $this->configuration['migration'];
-    if (!is_array($migration_ids)) {
-      $migration_ids = [$migration_ids];
-    }
-    if (!is_array($value)) {
-      $value = [$value];
-    }
-    $this->skipOnEmpty($value);
-    $self = FALSE;
-    /** @var \Drupal\migrate\Plugin\MigrationInterface[] $migrations */
-    $destination_ids = NULL;
-    $source_id_values = [];
-    $migrations = $this->migrationPluginManager->createInstances($migration_ids);
-    foreach ($migrations as $migration_id => $migration) {
-      if ($migration_id == $this->migration->id()) {
-        $self = TRUE;
-      }
-      if (isset($this->configuration['source_ids'][$migration_id])) {
-        $configuration = ['source' => $this->configuration['source_ids'][$migration_id]];
-        $source_id_values[$migration_id] = $this->processPluginManager
-          ->createInstance('get', $configuration, $this->migration)
-          ->transform(NULL, $migrate_executable, $row, $destination_property);
-      }
-      else {
-        $source_id_values[$migration_id] = $value;
-      }
-      // Break out of the loop as soon as a destination ID is found.
-      if ($destination_ids = $migration->getIdMap()->lookupDestinationId($source_id_values[$migration_id])) {
-        break;
-      }
-    }
-
-    if (!$destination_ids && !empty($this->configuration['no_stub'])) {
-      return NULL;
-    }
-
-    if (!$destination_ids && ($self || isset($this->configuration['stub_id']) || count($migrations) == 1)) {
-      // If the lookup didn't succeed, figure out which migration will do the
-      // stubbing.
-      if ($self) {
-        $migration = $this->migration;
-      }
-      elseif (isset($this->configuration['stub_id'])) {
-        $migration = $migrations[$this->configuration['stub_id']];
-      }
-      else {
-        $migration = reset($migrations);
-      }
-      $destination_plugin = $migration->getDestinationPlugin(TRUE);
-      // Only keep the process necessary to produce the destination ID.
-      $process = $migration->getProcess();
-
-      // We already have the source ID values but need to key them for the Row
-      // constructor.
-      $source_ids = $migration->getSourcePlugin()->getIds();
-      $values = [];
-      foreach (array_keys($source_ids) as $index => $source_id) {
-        $values[$source_id] = $source_id_values[$migration->id()][$index];
-      }
-
-      $stub_row = new Row($values + $migration->getSourceConfiguration(), $source_ids, TRUE);
-
-      // Do a normal migration with the stub row.
-      $migrate_executable->processRow($stub_row, $process);
-      $destination_ids = [];
-      try {
-        $destination_ids = $destination_plugin->import($stub_row);
-      }
-      catch (\Exception $e) {
-        $migration->getIdMap()->saveMessage($stub_row->getSourceIdValues(), $e->getMessage());
-      }
-
-      if ($destination_ids) {
-        $migration->getIdMap()->saveIdMapping($stub_row, $destination_ids, MigrateIdMapInterface::STATUS_NEEDS_UPDATE);
-      }
-    }
-    if ($destination_ids) {
-      if (count($destination_ids) == 1) {
-        return reset($destination_ids);
-      }
-      else {
-        return $destination_ids;
-      }
-    }
-  }
-
-  /**
-   * Skips the migration process entirely if the value is FALSE.
-   *
-   * @param mixed $value
-   *   The incoming value to transform.
-   *
-   * @throws \Drupal\migrate\MigrateSkipProcessException
-   */
-  protected function skipOnEmpty(array $value) {
-    if (!array_filter($value)) {
-      throw new MigrateSkipProcessException();
-    }
-  }
-
-}
+class Migration extends MigrationLookup { }

core/modules/migrate/src/Plugin/migrate/process/MigrationLookup.php

+<?php
+
+namespace Drupal\migrate\Plugin\migrate\process;
+
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Drupal\migrate\MigrateSkipProcessException;
+use Drupal\migrate\Plugin\MigratePluginManagerInterface;
+use Drupal\migrate\Plugin\MigrationPluginManagerInterface;
+use Drupal\migrate\Plugin\MigrateIdMapInterface;
+use Drupal\migrate\ProcessPluginBase;
+use Drupal\migrate\Plugin\MigrationInterface;
+use Drupal\migrate\MigrateExecutableInterface;
+use Drupal\migrate\Row;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+/**
+ * Looks up the value of a property based on a previous migration.
+ *
+ * It is important to maintain relationships among content coming from the
+ * source site. For example, on the source site, a given user account may
+ * have an ID of 123, but the Drupal user account created from it may have
+ * a uid of 456. The migration process maintains the relationships between
+ * source and destination identifiers in map tables, and this information
+ * is leveraged by the migration_lookup process plugin.
+ *
+ * Available configuration keys
+ * - migration: A single migration ID, or an array of migration IDs.
+ * - source_ids: (optional) An array keyed by migration IDs with values that are
+ *   a list of source properties.
+ * - stub_id: (optional) Identifies the migration which will be used to create
+ *   any stub entities.
+ * - no_stub: (optional) Prevents the creation of a stub entity when no
+ *   relationship is found in the migration map.
+ *
+ * Examples:
+ *
+ * Consider a node migration, where you want to maintain authorship. If you have
+ * migrated the user accounts in a migration named "users", you would specify
+ * the following:
+ *
+ * @code
+ * process:
+ *   uid:
+ *     plugin: migration_lookup
+ *     migration: users
+ *     source: author
+ * @endcode
+ *
+ * This takes the value of the author property in the source data, and looks it
+ * up in the map table associated with the users migration, returning the
+ * resulting user ID and assigning it to the destination uid property.
+ *
+ * The value of 'migration' can be a list of migration IDs. When using multiple
+ * migrations it is possible each use different source identifiers. In this
+ * case one can use source_ids which is an array keyed by the migration IDs
+ * and the value is a list of source properties.
+ *
+ * @code
+ * process:
+ *   uid:
+ *     plugin: migration_lookup
+ *       migration:
+ *         - users
+ *         - members
+ *       source_ids:
+ *         users:
+ *           - author
+ *         members:
+ *           - id
+ * @endcode
+ *
+ * If the migration_lookup plugin does not find the source ID in the migration
+ * map it will create a stub entity for the relationship to use. This stub is
+ * generated by the migration provided. In the case of multiple migrations the
+ * first value of the migration list will be used, but you can select the
+ * migration you wish to use by using the stub_id configuration key:
+ *
+ * @code
+ * process:
+ *   uid:
+ *     plugin: migration_lookup
+ *     migration:
+ *       - users
+ *       - members
+ *     stub_id: members
+ * @endcode
+ *
+ * In the above example, the value of stub_id selects the members migration to
+ * create any stub entities.
+ *
+ * To prevent the creation of a stub entity when no relationship is found in the
+ * migration map, use no_stub:
+ *
+ * @code
+ * process:
+ *   uid:
+ *     plugin: migration_lookup
+ *     migration: users
+ *     no_stub: true
+ *     source: author
+ * @endcode
+ *
+ * @see \Drupal\migrate\Plugin\MigrateProcessInterface
+ *
+ * @MigrateProcessPlugin(
+ *   id = "migration_lookup"
+ * )
+ */
+class MigrationLookup extends ProcessPluginBase implements ContainerFactoryPluginInterface {
+
+  /**
+   * The process plugin manager.
+   *
+   * @var \Drupal\migrate\Plugin\MigratePluginManager
+   */
+  protected $processPluginManager;
+
+  /**
+   * The migration plugin manager.
+   *
+   * @var \Drupal\migrate\Plugin\MigrationPluginManagerInterface
+   */
+  protected $migrationPluginManager;
+
+  /**
+   * The migration to be executed.
+   *
+   * @var \Drupal\migrate\Plugin\MigrationInterface
+   */
+  protected $migration;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function __construct(array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration, MigrationPluginManagerInterface $migration_plugin_manager, MigratePluginManagerInterface $process_plugin_manager) {
+    parent::__construct($configuration, $plugin_id, $plugin_definition);
+    $this->migrationPluginManager = $migration_plugin_manager;
+    $this->migration = $migration;
+    $this->processPluginManager = $process_plugin_manager;
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration = NULL) {
+    return new static(
+      $configuration,
+      $plugin_id,
+      $plugin_definition,
+      $migration,
+      $container->get('plugin.manager.migration'),
+      $container->get('plugin.manager.migrate.process')
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
+    $migration_ids = $this->configuration['migration'];
+    if (!is_array($migration_ids)) {
+      $migration_ids = [$migration_ids];
+    }
+    if (!is_array($value)) {
+      $value = [$value];
+    }
+    $this->skipOnEmpty($value);
+    $self = FALSE;
+    /** @var \Drupal\migrate\Plugin\MigrationInterface[] $migrations */
+    $destination_ids = NULL;
+    $source_id_values = [];
+    $migrations = $this->migrationPluginManager->createInstances($migration_ids);
+    foreach ($migrations as $migration_id => $migration) {
+      if ($migration_id == $this->migration->id()) {
+        $self = TRUE;
+      }
+      if (isset($this->configuration['source_ids'][$migration_id])) {
+        $configuration = ['source' => $this->configuration['source_ids'][$migration_id]];
+        $source_id_values[$migration_id] = $this->processPluginManager
+          ->createInstance('get', $configuration, $this->migration)
+          ->transform(NULL, $migrate_executable, $row, $destination_property);
+      }
+      else {
+        $source_id_values[$migration_id] = $value;
+      }
+      // Break out of the loop as soon as a destination ID is found.
+      if ($destination_ids = $migration->getIdMap()->lookupDestinationId($source_id_values[$migration_id])) {
+        break;
+      }
+    }
+
+    if (!$destination_ids && !empty($this->configuration['no_stub'])) {
+      return NULL;
+    }
+
+    if (!$destination_ids && ($self || isset($this->configuration['stub_id']) || count($migrations) == 1)) {
+      // If the lookup didn't succeed, figure out which migration will do the
+      // stubbing.
+      if ($self) {
+        $migration = $this->migration;
+      }
+      elseif (isset($this->configuration['stub_id'])) {
+        $migration = $migrations[$this->configuration['stub_id']];
+      }
+      else {
+        $migration = reset($migrations);
+      }
+      $destination_plugin = $migration->getDestinationPlugin(TRUE);
+      // Only keep the process necessary to produce the destination ID.
+      $process = $migration->getProcess();
+
+      // We already have the source ID values but need to key them for the Row
+      // constructor.
+      $source_ids = $migration->getSourcePlugin()->getIds();
+      $values = [];
+      foreach (array_keys($source_ids) as $index => $source_id) {
+        $values[$source_id] = $source_id_values[$migration->id()][$index];
+      }
+
+      $stub_row = new Row($values + $migration->getSourceConfiguration(), $source_ids, TRUE);
+
+      // Do a normal migration with the stub row.
+      $migrate_executable->processRow($stub_row, $process);
+      $destination_ids = [];
+      try {
+        $destination_ids = $destination_plugin->import($stub_row);
+      }
+      catch (\Exception $e) {
+        $migration->getIdMap()->saveMessage($stub_row->getSourceIdValues(), $e->getMessage());
+      }
+
+      if ($destination_ids) {
+        $migration->getIdMap()->saveIdMapping($stub_row, $destination_ids, MigrateIdMapInterface::STATUS_NEEDS_UPDATE);
+      }
+    }
+    if ($destination_ids) {
+      if (count($destination_ids) == 1) {
+        return reset($destination_ids);
+      }
+      else {
+        return $destination_ids;
+      }
+    }
+  }
+
+  /**
+   * Skips the migration process entirely if the value is FALSE.
+   *
+   * @param mixed $value
+   *   The incoming value to transform.
+   *
+   * @throws \Drupal\migrate\MigrateSkipProcessException
+   */
+  protected function skipOnEmpty(array $value) {
+    if (!array_filter($value)) {
+      throw new MigrateSkipProcessException();
+    }
+  }
+