Handler classes

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.