Writing D6 to D8 entity migrations

Some part of this page if out of date, mainly because of Migrations are plugins instead of configuration entities. This page was last updated in Feb 2015.

Setting up

You’ll need clones of Drupal 6, 7, and 8. They don’t have to be installed, just cloned.

D6: The install file so you can look at hook_schema implementation
D7: The *.install files can help you locate more information about what changed between 6 and 8 in the update functions.
D8: The entity class
D8: The source class. If it is not in core (which is likely), you will need to download yours from here. Source classes are only added to core with a full, tested migration. This will likely be the migration you are writing right now. Don't forget to add the relevant unit test as well.

Find an open issue

Visit the Migrate Drupal 6 into Drupal 8 meta issue to find an open issue to get started on.

Creating the migration config file

A good example of a complete file is core/modules/migrate_drupal/config/migrate.migration.d6_user_role.yml.

Create your new file in core/modules/migrate_drupal/config, naming it after what you are migrating.

In this example, I’m writing a D6 migration for Role.php, so I’ll name it:

Writing the contents of the migration config file

id

This matches the last part of the file name (Drupal version and migration)

Since the file is called migrate.migration.d6_user_role.yml, the id will be:

If the id and the filename don't align, then the entity won't load.

source

The source class, if one exists, is found in the core/modules/migrate_drupal/lib/Drupal/migrate_drupal/Plugin/migrate/source/d6 directory. For our example, that’s Role.php

Example:
Line 16 in
core/modules/migrate_drupal/lib/Drupal/migrate_drupal/Plugin/migrate/source/d6/Role.php

process

Process keys are

• For configuration entities, the public properties of the entity class (minus UUID, which is generated).
• For content entities, the keys in baseFieldDefinitions

See the handbook page for the currently available processes. The details will vary depending on the property, but you can start by listing the public properties as follows:

Example:
Lines 42 - 77 in
core/modules/user/lib/Drupal/user/Entity/Role.php

destination

The issue told me these values, but I can verify this by looking at D8
destination:

Example:
Line 18 of core/modules/user/lib/Drupal/user/Entity/Role.php

Writing integration tests for the migration (TDD)

Creating the dump file

1. First, create your file in core/modules/migrate_drupal/lib/Drupal/migrate_drupal/Tests/Dump. The naming convention is Drupal6EntityName.php
   
   Example:
   core/modules/migrate_drupal/lib/Drupal/migrate_drupal/Tests/Dump/Drupal6Role.php
2. Set up the skeleton, being sure to change the lines indicated:
   
   <?php
/**
* @file
* Contains \Drupal\migrate_drupal\Tests\Dump\Drupal6Role. <--Update this
*/

namespace Drupal\migrate_drupal\Tests\Dump;
use Drupal\Core\Database\Connection;

/**
* Database dump for testing role migration. <--Update this
*/
class Drupal6Role { <--Update this

  /**
   * @param \Drupal\Core\Database\Connection $database
   */
  public static function load(Connection $database) {

  [You will paste code here]

  }
}
3. Paste the dump code:
   You'll usually find the data you need in the Drupal 7 file modules/simpletest/tests/upgrade/drupal-6.filled.database.php For this example, we'll search for drupal-6.filled.database.php for the test "db_create_table('node_type'" and copy everything beginning with that line up to and including the next ->execute();
4. Update the function calls:
   
   1. db_create_table('role', array( becomes $database->schema()->createTable('role', array(
   2. db_insert('role')->fields(array( becomes $database->insert('role')->fields(array(

Test examples:
MigrateD6FilterFormatTest
Drupal6FilterFormat dump

Steps

1. load the migration
2. specify the dump
3. prepare for migration
4. run the import
5. load the result
6. assert it looks good
7. done

Creating the Simpletests

The following directions create the stub for the tests with a single assertion. If you can, create the full test files, but if not, stub in the tests by following this example.

Test files are located in core/modules/migrate_drupal/lib/Drupal/migrate_drupal/Tests/d6. The naming convention is MigrateEntityNameTest.php

Skeleton example:

Writing migration-specific process plugins

Many migrations will require migration-specific plugins. These require deep and specific knowledge of Drupal. You should feel free to move on to the next issue and leave those plugins to others. If you want to take a shot at them, moshe and chx will be your resources.