Chris@0: INTRODUCTION
Chris@0: ------------
Chris@0: The migrate_example module demonstrates how to implement custom migrations
Chris@0: for Drupal 8. It includes a group of "beer" migrations demonstrating a complete
Chris@0: simple migration scenario.
Chris@0: 
Chris@0: THE BEER SITE
Chris@0: -------------
Chris@0: In this scenario, we have a beer aficionado site which stores its data in MySQL
Chris@0: tables - there are content items for each beer on the site, user accounts with
Chris@0: profile data, categories to classify the beers, and user-generated comments on
Chris@0: the beers. We want to convert this site to Drupal with just a few modifications
Chris@0: to the basic structure.
Chris@0: 
Chris@0: To make the example as simple as to run as possible, the source data is placed
Chris@0: in tables directly in your Drupal database - in most real-world scenarios, your
Chris@0: source data will be in an external database. The migrate_example_setup submodule
Chris@0: creates and populates these tables, as well as configuring your Drupal 8 site
Chris@0: (creating a node type, vocabulary, fields, etc.) to receive the data.
Chris@0: 
Chris@0: STRUCTURE
Chris@0: ---------
Chris@0: There are two primary components to this example:
Chris@0: 
Chris@0: 1. Migration configuration, in the config/install directory. These YAML files
Chris@0:    describe the migration process and provide the mappings from the source data
Chris@0:    to Drupal's destination entities. The YAML file names are prefixed with
Chris@0:    'migrate_plus.migration.' (because, reading from right to left, they define
Chris@0:    "migration" configuration entities, and the configuration entity type is
Chris@0:    defined by the "migrate_plus" module).
Chris@0: 
Chris@0: 2. Source plugins, in src/Plugin/migrate/source. These are referenced from the
Chris@0:    configuration files, and provide the source data to the migration processing
Chris@0:    pipeline, as well as manipulating that data where necessary to put it into
Chris@0:    a canonical form for migrations.
Chris@0: 
Chris@0: UNDERSTANDING THE MIGRATIONS
Chris@0: ----------------------------
Chris@0: The YAML and PHP files are copiously documented in-line. To best understand
Chris@0: the concepts described in a more-or-less narrative form, it is recommended you
Chris@0: read the files in the following order:
Chris@0: 
Chris@0: 1. migrate_plus.migration_group.beer.yml
Chris@0: 2. migrate_plus.migration.beer_term.yml
Chris@0: 3. BeerTerm.php
Chris@0: 4. migrate_plus.migration.beer_user.yml
Chris@0: 5. BeerUser.php
Chris@0: 6. migrate_plus.migration.beer_node.yml
Chris@0: 7. BeerNode.php
Chris@0: 8. migrate_plus.migration.beer_comment.yml
Chris@0: 9. BeerComment.php
Chris@0: 
Chris@0: RUNNING THE MIGRATIONS
Chris@0: ----------------------
Chris@0: The migrate_tools module (https://www.drupal.org/project/migrate_tools) provides
Chris@0: the tools you need to perform migration processes. At this time, the web UI only
Chris@0: provides status information - to perform migration operations, you need to use
Chris@0: the drush commands.
Chris@0: 
Chris@0: # Enable the tools and the example module if you haven't already.
Chris@0: drush en -y migrate_tools,migrate_example
Chris@0: 
Chris@0: # Look at the migrations. Just look at them. Notice that they are displayed in
Chris@0: # the order they will be run, which reflects their dependencies. For example,
Chris@0: # because the node migration references the imported terms and users, it must
Chris@0: # run after those migrations have been run.
Chris@0: drush ms               # Abbreviation for migrate-status
Chris@0: 
Chris@0: # Run the import operation for all the beer migrations.
Chris@0: drush mi --group=beer  # Abbreviation for migrate-import
Chris@0: 
Chris@0: # Look at what you've done! Also, visit the site and see the imported content,
Chris@0: # user accounts, etc.
Chris@0: drush ms
Chris@0: 
Chris@0: # Look at the duplicate username message.
Chris@0: drush mmsg beer_user   # Abbreviation for migrate-messages
Chris@0: 
Chris@0: # Run the rollback operation for all the migrations (removing all the imported
Chris@0: # content, user accounts, etc.). Note that it will rollback the migrations in
Chris@0: # the opposite order as they were imported.
Chris@0: drush mr --group=beer  # Abbreviation for migrate-rollback
Chris@0: 
Chris@0: # You can import specific migrations.
Chris@0: drush mi beer_term,beer_user
Chris@0: # At this point, go look at your content listing - you'll see beer nodes named
Chris@0: # "Stub", generated from the user's favbeers references.
Chris@0: 
Chris@0: drush mi beer_node,beer_comment
Chris@0: # Refresh your content listing - the stub nodes have been filled with real beer!
Chris@0: 
Chris@0: # You can rollback specific migrations.
Chris@0: drush mr beer_comment,beer_node