www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/migrate_plus/migrate_example/README.txt

   1 INTRODUCTION
   2 ------------
   3 The migrate_example module demonstrates how to implement custom migrations
   4 for Drupal 8. It includes a group of "beer" migrations demonstrating a complete
   5 simple migration scenario.
   6
   7 THE BEER SITE
   8 -------------
   9 In this scenario, we have a beer aficionado site which stores its data in MySQL
  10 tables - there are content items for each beer on the site, user accounts with
  11 profile data, categories to classify the beers, and user-generated comments on
  12 the beers. We want to convert this site to Drupal with just a few modifications
  13 to the basic structure.
  14
  15 To make the example as simple as to run as possible, the source data is placed
  16 in tables directly in your Drupal database - in most real-world scenarios, your
  17 source data will be in an external database. The migrate_example_setup submodule
  18 creates and populates these tables, as well as configuring your Drupal 8 site
  19 (creating a node type, vocabulary, fields, etc.) to receive the data.
  20
  21 STRUCTURE
  22 ---------
  23 There are two primary components to this example:
  24
  25 1. Migration configuration, in the config/install directory. These YAML files
  26    describe the migration process and provide the mappings from the source data
  27    to Drupal's destination entities. The YAML file names are prefixed with
  28    'migrate_plus.migration.' (because, reading from right to left, they define
  29    "migration" configuration entities, and the configuration entity type is
  30    defined by the "migrate_plus" module).
  31
  32 2. Source plugins, in src/Plugin/migrate/source. These are referenced from the
  33    configuration files, and provide the source data to the migration processing
  34    pipeline, as well as manipulating that data where necessary to put it into
  35    a canonical form for migrations.
  36
  37 UNDERSTANDING THE MIGRATIONS
  38 ----------------------------
  39 The YAML and PHP files are copiously documented in-line. To best understand
  40 the concepts described in a more-or-less narrative form, it is recommended you
  41 read the files in the following order:
  42
  43 1. migrate_plus.migration_group.beer.yml
  44 2. migrate_plus.migration.beer_term.yml
  45 3. BeerTerm.php
  46 4. migrate_plus.migration.beer_user.yml
  47 5. BeerUser.php
  48 6. migrate_plus.migration.beer_node.yml
  49 7. BeerNode.php
  50 8. migrate_plus.migration.beer_comment.yml
  51 9. BeerComment.php
  52
  53 RUNNING THE MIGRATIONS
  54 ----------------------
  55 The migrate_tools module (https://www.drupal.org/project/migrate_tools) provides
  56 the tools you need to perform migration processes. At this time, the web UI only
  57 provides status information - to perform migration operations, you need to use
  58 the drush commands.
  59
  60 # Enable the tools and the example module if you haven't already.
  61 drush en -y migrate_tools,migrate_example
  62
  63 # Look at the migrations. Just look at them. Notice that they are displayed in
  64 # the order they will be run, which reflects their dependencies. For example,
  65 # because the node migration references the imported terms and users, it must
  66 # run after those migrations have been run.
  67 drush ms               # Abbreviation for migrate-status
  68
  69 # Run the import operation for all the beer migrations.
  70 drush mi --group=beer  # Abbreviation for migrate-import
  71
  72 # Look at what you've done! Also, visit the site and see the imported content,
  73 # user accounts, etc.
  74 drush ms
  75
  76 # Look at the duplicate username message.
  77 drush mmsg beer_user   # Abbreviation for migrate-messages
  78
  79 # Run the rollback operation for all the migrations (removing all the imported
  80 # content, user accounts, etc.). Note that it will rollback the migrations in
  81 # the opposite order as they were imported.
  82 drush mr --group=beer  # Abbreviation for migrate-rollback
  83
  84 # You can import specific migrations.
  85 drush mi beer_term,beer_user
  86 # At this point, go look at your content listing - you'll see beer nodes named
  87 # "Stub", generated from the user's favbeers references.
  88
  89 drush mi beer_node,beer_comment
  90 # Refresh your content listing - the stub nodes have been filled with real beer!
  91
  92 # You can rollback specific migrations.
  93 drush mr beer_comment,beer_node