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