Destination handlers

Destination handlers

A destination handler adds behavior to the processing of one or more entity types. It does so by implementing (in addition to a constructor registering the type(s) it handles) one or more of the following methods:

public function fields()

If implemented, this should return an array of fields to be added to the list of available destination fields maintained by Migrate. This is primarily for documentation purposes - Migration classes can map source values to these fields whether or not they're explicitly declared, but providing them here makes them visible in the migration info pages and avoids warnings about mapping to non-existent fields.

The array returned should be keyed by the fieldname as the contrib module expects it in the entity being imported, and the values will be displayed on the migration info pages. It is recommended that this string have the module name prepended with a colon, to make it easy to determine the source of each field.

Note that for many contrib modules, all that is necessary is to set the right value on the entity before it is saved, so you will often find that fields() is all you need.

public function prepare($entity, stdClass $row)

The prepare method is called shortly before the entity is saved (e.g., for nodes shortly before node_save()) is called, and is an opportunity to manipulate the entity object before it is saved. The $entity object represents the entity as it is to be saved (perhaps having already been modified by other prepare() methods), and $row is the original source data, should you need to refer to that.

public function complete($entity, stdClass $row)

Similar to the prepare method, but called immediately after the entity is saved, this is most useful if you need to do something (such as save related data rows) that requires the ID of the entity that was imported.

So, here is a complete example of a destination handler for the Pathauto module:

// We base our destination handler, naturally, on MigrateDestinationHandler
class MigratePathautoHandler extends MigrateDestinationHandler {
  public function __construct() {
    // By registering these three types, we ensure that our methods
    // will only be called for destinations of these types.
    $this->registerTypes(array('node', 'user', 'taxonomy_term'));
  }

  // The Migrate module's field mapping process only sets top-level values
  // in the destination entity, but disabling pathauto during migration requires
  // a value within the path array. So, we declare a pseudo-field to which we
  // can map the desired value.
  public function fields() {
    return array(
      'pathauto' =>
        t('Pathauto: Perform aliasing (set to 0 to prevent alias generation during migration'),
    );
  }

  // So, just before the entity is saved, we check to see if our pseudo-field
  // is present. If so, we set up the path[] array appropriately, and remove
  // the pseudo-field just to make sure it doesn't get in the way of anything.
  public function prepare($entity, stdClass $row) {
    if (isset($entity->pathauto)) {
      if (!isset($entity->path)) {
        $entity->path = array();
      }
      $entity->path['pathauto'] = $entity->pathauto;
      if (!isset($entity->path['alias'])) {
        $entity->path['alias'] = '';
      }
      unset($entity->pathauto);
    }
  }
}