Migrations and migration groups

For the migration classes you implement to be available for reviewing status, running imports, etc., instances of them must be registered. There are two methods of getting your migrations and migration groups registered:

hook_migrate_api()

This is the recommended means of registering your migrations and migration groups if they're static - that is, if you don't need to pick-and-choose at runtime what migrations to register or what arguments to set for them.

It's recommended that you explicitly assign your migrations to a migration group (if you don't, they will be in the 'default' group). Groups can be registered in the API array by including a 'groups' key, whose value is an array keyed by the group machine name and the value an array of arguments for the group. The 'title' argument is special - this is the name of the group as it will be presented in the UI (if you omit the title, the machine name will be displayed instead). Any other arguments are saved as part of the group, and made available to any migrations in the group when they are instantiated.

The 'migrations' key should be an array, keyed by the migration machine name, with the value an array of arguments. 'class_name' is the one required argument (although 'group_name' is recommended) - any others are class-specific arguments, and are passed in the $arguments array to the class constructor.

Note that you can pass a list of hooks to disable during migration through the arguments - see Disable hooks during migration for details.

function example_migrate_api() {
  $api = array(
    'api' => 2,
    'groups' => array(
      'example' => array(
        'title' => t('Example'),
        'default_format' => 'filtered_html',
      ),
    ),
    'migrations' => array(
      'ExampleUser' => array(
        'class_name' => 'ExampleUserMigration',
        'group_name' => 'example',
      ),
      'ExampleArticle' => array(
        'class_name' => 'ExampleArticleMigration',
        'group_name' => 'example',
      ),
    ),
  );
  return $api;
}

After adding new migrations, or making changes to the arguments of previously-registered migrations, if you want them to be recognized by Migrate, you need to:

1. Clear the Drupal cache, so any new classes are added to the Drupal cache registry.
2. Perform the registration, either with drush migrate-register or by visiting admin/content/migrate/configure and clicking the "Register statically-defined classes" button.

MigrationBase::registerMigration()

This would typically be used when the arguments, or the list of migrations to register, is determined dynamically (as when you have a UI letting users choose what to migrate). The first argument is the class name to be instantiated, the second the machine name by which the migration will be known, and the third argument is an array of arguments to be passed to the migration constructor:

MigrationBase::registerMigration('ExampleUserMigration', 'ExampleUser', array('group_name' => 'example', 'default_uid' => 1));

Destination and field handler classes

Destination and field handler classes defined by your module must be explicitly registered in hook_migrate_api as follows:

function example_migrate_api() {
  $api = array(
    'api' => 2,
    'destination handlers' => array(
      'ExampleNodeHandler',
    ),
    'field handlers' => array(
      'ExampleCustomFieldHandler',
    )
  );
  return $api;
}