Handlers are classes which enable you to add additional behavior to the processing of data being imported. These are usually used to support migration into contributed or custom modules that maintain their own data connected to core entities. Most of the time this will be related to custom field types.

Two kinds of handlers are implemented in the Migrate module:

  1. Destination handlers, for manipulating the processing of entire destination objects. (ex: MigrateFieldsEntityHandler
  2. Field handlers, for manipulating specific fields (in the narrow sense of fields defined by the Field API in Drupal 7, or CCK in Drupal 6). Ex. MigrateTextFieldHandler, MigrateFieldHandler, ....

Both kinds of handlers are derived from the MigrateHandler class, which provides the following base functionality.

Dependencies - If a handler must not be invoked until some other handler has executed first, it can declare dependencies in its constructor, passing the class names of handlers which must execute first.

Types handled - To be invoked, a handler must indicate what "types" it operates on. For destination handlers, this would be the entity type ('node', 'user', etc.);

class MigrateFieldsEntityHandler extends MigrateDestinationHandler {
  public function __construct() {
    $this->registerTypes(array('entity'));
  }
  ...

for field handlers, it would be the field type ('text', 'number_integer', 'taxonomy_term_reference', etc.).

class MigrateTextFieldHandler extends MigrateFieldHandler {
  public function __construct() {
    $this->registerTypes(array('text', 'text_long', 'text_with_summary'));
  }
  ...

To do so, it will call $this->registerTypes in its constructor, passing an array of type machine names.

So, a field handler for a custom complex field built out of text fields, which must run after the text field handler, might have a constructor like:

public function __construct() {
  $this->dependencies = array('MigrateTextFieldHandler');
  $this->registerTypes(array('my_custom_field_type'));
}

Registering Your Handler

Your handler isn't going to be recognized by the Migrate module until you declare it in an implementation of hook_migrate_api, such as:

function myImport_migrate_api() {
  $api = array(
    'api' => 2,
    'field handlers' => array('MigrateFooFieldHandler'),
  );
  return $api;
}

The Migrate Extras module is a good example of this.

Comments

zorroposada’s picture

Can you please explain how to use handler classes with migration classes?
How to call or use a specific handler class from within a migration class? Is that the right way of doing it?

I want to migrate Polls from a Drupal6 site into a Drupal7 site. I found code in poll.inc

Can you extend MigratePollEntityHandler with your own Migration Class?

Bezude’s picture

It would be useful to point out on this handler page that in order to use a custom handler you have to add a 'field handlers' property to your module's implementation of hook_migrate_api. This points to an array that contains the class names of your handlers.

function myImport_migrate_api() {
  $api = array(
    'api' => 2,
    'field handlers' => array('MigrateFooFieldHandler'),
  );
  return $api;
}