clean install

web/modules/migrate_plus/migrate_example/config/install/migrate_plus.migration.beer_node.yml

@@ -0,0 +1,55 @@
+# Migration configuration for beer content.
+id: beer_node
+label: Beers of the world
+migration_group: beer
+migration_tags:
+  - example
+source:
+  plugin: beer_node
+destination:
+  plugin: entity:node
+process:
+  # Hardcode the destination node type (bundle) as 'migrate_example_beer'.
+  type:
+    plugin: default_value
+    default_value: migrate_example_beer
+  title: name
+  nid: bid
+  uid:
+    plugin: migration_lookup
+    migration: beer_user
+    source: aid
+  sticky:
+    plugin: default_value
+    default_value: 0
+  field_migrate_example_country: countries
+  field_migrate_example_beer_style:
+    plugin: migration_lookup
+    migration: beer_term
+    source: terms
+  # Some Drupal fields may have multiple components we may want to set
+  # separately. For example, text fields may have summaries (teasers) in
+  # addition to the full text value. We use / to separate the field name from
+  # the internal field value being set, and put it in quotes because / is a
+  # YAML special character.
+  'body/value': body
+  'body/summary': excerpt
+# Our beer nodes have references to terms and users, so we want those to be
+# imported first. We make that dependency explicit here - by putting those
+# migrations under the 'required' key, we ensure that the tools will prevent
+# us from running the beer_node migration unless the beer_term and beer_user
+# migrations are complete (although we can override the dependency check by
+# passing --force to the drush migrate-import command). We can also add
+# 'optional' dependencies - these affect the order in which migrations are
+# displayed, and run by default, but does not force you run them in that
+# order.
+# The general rule of thumb is that any migrations referenced by migration
+# process plugins should be required here.
+migration_dependencies:
+  required:
+    - beer_term
+    - beer_user
+dependencies:
+  enforced:
+    module:
+      - migrate_example

web/modules/migrate_plus/migrate_example/config/install/migrate_plus.migration.beer_term.yml

@@ -0,0 +1,91 @@
+# A "migration" is, in technical terms, a plugin whose configuration describes
+# how to read source data, process it (generally by mapping source fields to
+# destination fields), and write it to Drupal.
+
+# The machine name for a migration, used to uniquely identify it.
+id: beer_term
+
+# A human-friendly description of the migration.
+label: Migrate style categories from the source database to taxonomy terms
+
+# The machine name of the group containing this migration (which contains shared
+# configuration to be merged with our own configuration here).
+migration_group: beer
+
+# The category or tag for the migration.
+migration_tags:
+  - example
+
+# Every migration must have a source plugin, which controls the delivery of our
+# source data. In this case, our source plugin has the name "beer_term", which
+# Drupal resolves to the PHP class defined in
+# src/Plugin/migrate/source/BeerTerm.php.
+source:
+  plugin: beer_term
+
+# Every migration must also have a destination plugin, which handles writing
+# the migrated data in the appropriate form for that particular kind of data.
+# Most Drupal content is an "entity" of one type or another, and we need to
+# specify what entity type we are populating (in this case, taxonomy terms).
+# Unlike the source plugin (which is specific to our particular scenario), this
+# destination plugin is implemented in Drupal itself.
+destination:
+  plugin: entity:taxonomy_term
+
+# Here's the meat of the migration - the processing pipeline. This describes how
+# each destination field is to be populated based on the source data. For each
+# destination field, one or more process plugins may be invoked.
+process:
+  # The simplest process plugin is named 'get' - it is the default plugin, so
+  # does not need to be explicitly named. It simply copies the source value
+  # (the 'style' field from the source database in this case) to the destination
+  # field (the taxonomy term 'name' field). You can see we simply copy the
+  # source 'details' field to destination 'description' field in the same way.
+  name: style
+  description: details
+
+  # Here is a new plugin - default_value. In its simplest usage here, it is used
+  # to hard-code a destination value, the vid (vocabulary ID) our taxonomy terms
+  # should be assigned to. It's important to note that while above the right
+  # side of the mappings was a source field name, here the right side of the
+  # 'default_value:' line is an actual value.
+  vid:
+    plugin: default_value
+    default_value: migrate_example_beer_styles
+
+  # Here's another new plugin - migration. When importing data from another
+  # system, typically the unique identifiers for items on the destination side
+  # are not the same as the identifiers were on the source side. For example, in
+  # our style data the term names are the unique identifiers for each term,
+  # while in Drupal each term is assigned a unique integer term ID (tid). When
+  # any such items are referenced in Drupal, the reference needs to be
+  # translated from the old ID ('ale') to the new ID (1). The migration
+  # framework keeps track of the relationships between source and destination
+  # IDs in map tables, and the migration plugin is the means of performing a
+  # lookup in those map tables during processing.
+  parent:
+    plugin: migration_lookup
+    # Here we reference the migration whose map table we're performing a lookup
+    # against. You'll note that in this case we're actually referencing this
+    # migration itself, since category parents are imported by the same
+    # migration. This works best when we're sure the parents are imported
+    # before the children, and in this case our source plugin is guaranteeing
+    # that.
+    migration: beer_term
+    # 'style_parent' is the parent reference field from the source data. The
+    # result of this plugin is that the destination 'parent' field is populated
+    # with the Drupal term ID of the referenced style (or NULL if style_parent
+    # was empty).
+    source: style_parent
+
+# We'll learn more about dependencies in beer_node - here, we leave them empty.
+migration_dependencies: {}
+
+# By default, configuration entities (like this migration) are not automatically
+# removed when the migration which installed them is uninstalled. To have your
+# migrations uninstalled with your migration module, add an enforced dependency
+# on your module.
+dependencies:
+  enforced:
+    module:
+      - migrate_example

web/modules/migrate_plus/migrate_example/config/install/migrate_plus.migration.beer_user.yml

@@ -0,0 +1,107 @@
+# Migration configuration for user accounts. We've described most of what goes
+# into migration configuration in migrate_plus.migration.beer_term.yml, so won't
+# repeat that here.
+id: beer_user
+label: Beer Drinkers of the world
+migration_group: beer
+migration_tags:
+  - example
+source:
+  plugin: beer_user
+destination:
+  plugin: entity:user
+process:
+  pass: password
+  mail: email
+  init: email
+  status: status
+  roles:
+    plugin: default_value
+    default_value: 2
+
+  # Here's a new process plugin - make_unique_entity_field. Our source site allowed there
+  # to be multiple user accounts with the same username, but Drupal wants
+  # usernames to be unique. This plugin allows us to automatically generate
+  # unique usernames when we detect collisions.
+  name:
+    plugin: make_unique_entity_field
+    # The name of the source field containing the username.
+    source: username
+    # These next two settings identify the destination-side field to check for
+    # duplicates. They say "see if the incoming 'name' matches any existing
+    # 'name' field in any 'user' entity".
+    entity_type: user
+    field: name
+    # Finally, this specifies a string to use between the original value and the
+    # sequence number appended to make the value unique. Thus, the first 'alice'
+    # account gets the name 'alice' in Drupal, and the second one gets the name
+    # 'alice_1'.
+    postfix: _
+
+  # Another new process plugin - callback. This allows us to filter an incoming
+  # source value through an arbitrary PHP function. The function called must
+  # have one required argument.
+  created:
+    plugin: callback
+    # The 'registered' timestamp in the source data is a string of the form
+    # 'yyyy-mm-dd hh:mm:ss', but Drupal wants a UNIX timestamp for 'created'.
+    source: registered
+    callable: strtotime
+
+  # Our source data only has a single timestamp value, 'registered', which we
+  # want to use for all four of Drupal's user timestamp fields. We could
+  # duplicate the callback plugin we used for 'created' above - but we have a
+  # shortcut. Putting an @ sign at the beginning of the source value indicates
+  # that it is to be interpreted as a *destination* field name instead of a
+  # *source* field name. Thus, if a value we need in more than one place
+  # requires some processing beyond simply copying it directly, we can perform
+  # that processing a single time and use the result in multiple places.
+  changed: '@created'
+  access: '@created'
+  login: '@created'
+
+  # Yet another new process plugin - static_map. We're making a transformation
+  # in how we represent gender data - formerly it was integer values 0 for male
+  # and 1 for female, but in our modern Drupal site we will be making this a
+  # free-form text field, so we want to replace the obscure integers with
+  # simple strings.
+  field_migrate_example_gender:
+    plugin: static_map
+    # Specify the source field we're reading (containing 0's and 1's).
+    source: sex
+    # Tell it to transform 0 to 'Male', and 1 to 'Female'.
+    map:
+      0: Male
+      1: Female
+    # If the input is missing, leave the field empty. Without this, an empty
+    # or invalid source value would cause the user record to be skipped
+    # entirely.
+    bypass: true
+
+  # This looks like a simple migration process plugin, but there's magic
+  # happening here. We import nodes after terms and users, because they have
+  # references to terms and users, so of course the terms and users must be
+  # migrated first - right? However, the favbeers field is a reference to the
+  # beer nodes which haven't yet been migrated - we have a circular relationship
+  # between users and nodes. The way the migration system resolves this
+  # situation is by creating "stubs". In this case, because no beer nodes have
+  # been created, each time a beer is looked up against the beer_node migration
+  # nothing is found, and by default the migration process plugin creates an
+  # empty stub node as a placeholder so the favbeers reference field has
+  # something to point to. The stub is recorded in the beer_node map table, so
+  # when that migration runs it knows that each incoming beer should overwrite
+  # its stub instead of creating a new node.
+  field_migrate_example_favbeers:
+    plugin: migration_lookup
+    source: beers
+    migration: beer_node
+
+migration_dependencies: {}
+
+# When a module is creating a custom content type it needs to add an 
+# enforced dependency to itself, otherwise the content type will persist
+# after the module is disabled. See: https://www.drupal.org/node/2629516.
+dependencies:
+  enforced:
+    module:
+      - migrate_example

web/modules/migrate_plus/migrate_example/config/install/migrate_plus.migration_group.beer.yml

@@ -0,0 +1,38 @@
+# A "migration group" is - surprise! - a group of migrations. It is used to
+# group migrations for display by our tools, and to perform operations on a
+# specific set of migrations. It can also be used to hold any configuration
+# common to those migrations, so it doesn't have to be duplicated in each one.
+
+# The machine name of the group, by which it is referenced in individual
+# migrations.
+id: beer
+
+# A human-friendly label for the group.
+label: Beer Imports
+
+# More information about the group.
+description: A few simple beer-related imports, to demonstrate how to implement migrations.
+
+# Short description of the type of source, e.g. "Drupal 6" or "WordPress".
+source_type: Custom tables
+
+# Here we add any default configuration settings to be shared among all
+# migrations in the group. For this example, the source tables are in the
+# Drupal (default) database, but usually if your source data is in a
+# database it will be external.
+shared_configuration:
+  # Specifying 'source' here means that this configuration will be merged into
+  # the 'source' configuration of each migration.
+  source:
+    # A better practice for real-world migrations would be to add a database
+    # connection to your external database in settings.php and reference its
+    # key here.
+    key: default
+
+# As with the migration configuration (see beer_term), we add an enforced
+# dependency so the migration_group configuration will be removed on module
+# uninstall.
+dependencies:
+  enforced:
+    module:
+      - migrate_example