Commonly implemented Migration methods

While simple migrations may get by with just a constructor, in many real-world cases you'll find a need to implement one or more of these Migration class methods:

• prepareRow($row)
• prepare($entity, stdClass $row)
• complete($entity, stdClass $row)
• createStub(Migration $migration, array $source_id)

Note: if you have generic classes used for common configuration and mapping that implement one of the common migration methods listed below, any class that extends the generic class that uses the same methods in the generic class should call the parent method. For example, if your generic class has a prepare() method, and you need one in your extended class, add the following line to your extended class: parent::prepare($entity,$row);. prepareRow() should always have the code added as per the example below.

function prepareRow($row)

The prepareRow() method is called by the source class next() method, after loading the data row. The argument $row is a stdClass object containing the raw data as provided by the source. There are two primary reasons to implement prepareRow():

1. To modify the data row before it passes through any further methods and handlers: for example, fetching related data, splitting out source fields, combining or creating new source fields based on some logic.
2. To conditionally skip a row (by returning FALSE).

Consider this example, where there is additional data not directly accessible to the source class (e.g., the source is an XML feed and there's also related data from a database, or vice versa):

public function prepareRow($row) {
  // Always include this fragment at the beginning of every prepareRow()
  // implementation, so parent classes can ignore rows.
  if (parent::prepareRow($row) === FALSE) {
    return FALSE;
  }

  $related_data = $this->getRelatedData($row->id);
  // If marked as spam in the related data, skip this row
  if ($related_data->spam) {
    return FALSE;
  }

  // Add the related data of interest
  $row->foo = $related_data->foo;
  $row->bar = $related_data->bar;
  return TRUE;
}

It is important to note that rejected rows in prepareRow() are not removed from the total rows reported by drush migrate-status or the migrate dashboard - the counts reported there are the total rows available to the source, and rows which will be rejected by prepareRow() on import cannot be predicted.

To get the source key for the current row, use the following:

$row_source_key = $this->source->getCurrentKey();
// $row_source_key is an array whose keys are those passed for the Migrate map creation.

To record an error message for the current row

If you wish to record an error, use $this->queueMessage('your message text') and it will appear among the messages for this migration, automatically including the source ID.
Note: don't use $this->setMessage('message text') in prepareRow().

function prepare(stdClass $entity, stdClass $row)

The Migration class prepare() method is called by the destination class prepare() method, after it has called all field-level prepare() methods and immediately before the destination object is saved. The $entity argument is the destination object as populated by the initial field mappings and manipulated by the field-level methods; the $row argument is an object containing the data after prepareRow() and any callbacks have been applied. The prepare() method is the last chance to manipulate the destination object before it is saved to the Drupal database. It is important to remember that, since it is called after the field handlers, fields will be in their fully-expanded forms (i.e., in Drupal 7 a text field value will be at $entity->field_textual_data['und'][0]['value'] rather than simply $entity->field_textual_data).

This is an example for a node migration:

public function prepare($entity, stdClass $row) {
  // Let's pretend we couldn't have done this as easily in prepareRow...
  $entity->title = 'My site: ' . $row->source_title;
}

To record an error message in prepare()

If you wish to record an error, use $this->saveMessage('your message text'). Do not use $this->queueMessage('your message text') in prepare(), because message will be assigned to the next row.

function complete($entity, stdClass $row)

The Migration class complete() method is analogous to prepare(), but is called immediately after the complete destination object is saved. This may be used to do application-specific logging, or to update additional tables related to the object - it's mainly used when you need the Drupal ID of the newly-created object.

public function complete($entity, stdClass $row) {
  // Load term.
  $term = taxonomy_term_load($entity->tid);
  
  // Localized taxonomy term.
  $context = array(
    'term',
    $term->tid,
    'description'
  );
  i18n_string_textgroup('taxonomy')->update_translation($context, 'fr', $row->description_fr);
}

function createStub(Migration $migration, array $source_id)

If a migration's destination objects could potentially be referenced during migration before they run through migration themselves, consider defining a createStub() method for the migration. This method should create a simple object of the desired type, and return its ID (or FALSE if it could not be created). See Chickens and eggs: using stubs for more information.