Last updated August 22, 2012. Created by mikeryan on December 24, 2010.
Edited by jordojuice, twom, StuartDH, drewish. Log in to edit this page.

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.);

<?php
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.).

<?php
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:

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

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

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?

drush cc all

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;
}