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 migrations and config/install directories.
  26    These YAML files describe the migration process and provide the mappings from
  27    the source data to Drupal's destination entities. The difference between the
  28    two possible directories:
  29
  30    a. Files in the migrations directory provide configuration directly for the
  31    migration plugins. The filenames are of the form <migration ID>.yml. This
  32    approach is recommended when your migration configuration is fully hardcoded
  33    and does not need to be overridden (e.g., you don't need to change the URL to
  34    a source web service through an admin UI). While developing migrations,
  35    changes to these files require at most a 'drush cr' to load your changes.
  36
  37    b. Files in the config/install directory provide migration configuration as
  38    configuration entities, and have names of the form
  39    migrate_plus.migration.<migration ID>.yml ("migration" because they define
  40    entities of the "migration" type, and "migrate_plus" because that is the
  41    module which implements the "migration" type). Migrations defined in this way
  42    may have their configuration modified (in particular, through a web UI) by
  43    loading the configuration entity, modifying its configuration, and saving the
  44    entity. When developing, to get edits to the .yml files in config/install to
  45    take effect in active configuration, use the config_devel module.
  46
  47    Configuration in either type of file is identical - the only differences are
  48    the directories and filenames.
  49
  50 2. Source plugins, in src/Plugin/migrate/source. These are referenced from the
  51    configuration files, and provide the source data to the migration processing
  52    pipeline, as well as manipulating that data where necessary to put it into
  53    a canonical form for migrations.
  54
  55 UNDERSTANDING THE MIGRATIONS
  56 ----------------------------
  57 The YAML and PHP files are copiously documented in-line. To best understand
  58 the concepts described in a more-or-less narrative form, it is recommended you
  59 read the files in the following order:
  60
  61 1. migrate_plus.migration_group.beer.yml
  62 2. migrate_plus.migration.beer_term.yml
  63 3. BeerTerm.php
  64 4. migrate_plus.migration.beer_user.yml
  65 5. BeerUser.php
  66 6. migrate_plus.migration.beer_node.yml
  67 7. BeerNode.php
  68 8. migrate_plus.migration.beer_comment.yml
  69 9. BeerComment.php
  70
  71 RUNNING THE MIGRATIONS
  72 ----------------------
  73 The migrate_tools module (https://www.drupal.org/project/migrate_tools) provides
  74 the tools you need to perform migration processes. At this time, the web UI only
  75 provides status information - to perform migration operations, you need to use
  76 the drush commands.
  77
  78 # Enable the tools and the example module if you haven't already.
  79 drush en -y migrate_tools,migrate_example
  80
  81 # Look at the migrations. Just look at them. Notice that they are displayed in
  82 # the order they will be run, which reflects their dependencies. For example,
  83 # because the node migration references the imported terms and users, it must
  84 # run after those migrations have been run.
  85 drush ms               # Abbreviation for migrate-status
  86
  87 # Run the import operation for all the beer migrations.
  88 drush mi --group=beer  # Abbreviation for migrate-import
  89
  90 # Look at what you've done! Also, visit the site and see the imported content,
  91 # user accounts, etc.
  92 drush ms
  93
  94 # Look at the duplicate username message.
  95 drush mmsg beer_user   # Abbreviation for migrate-messages
  96
  97 # Run the rollback operation for all the migrations (removing all the imported
  98 # content, user accounts, etc.). Note that it will rollback the migrations in
  99 # the opposite order as they were imported.
 100 drush mr --group=beer  # Abbreviation for migrate-rollback
 101
 102 # You can import specific migrations.
 103 drush mi beer_term,beer_user
 104 # At this point, go look at your content listing - you'll see beer nodes named
 105 # "Stub", generated from the user's favbeers references.
 106
 107 drush mi beer_node,beer_comment
 108 # Refresh your content listing - the stub nodes have been filled with real beer!
 109
 110 # You can rollback specific migrations.
 111 drush mr beer_comment,beer_node