Last updated December 22, 2010. Created by frankcarey on March 27, 2009.
Edited by mikeryan, Les Lim, cedarm, matason. Log in to edit this page.
Migrate API - new in migrate-1.0-beta4 and beyond.
Important: This documentation refers to Migrate V1 only! Migrate V2 (on Drupal 6 and Drupal 7) has been completely redesigned, this documentation does not apply.
Providing Integration with migrate is similar to views integration. You implement hook_migrate_api() in your MODULE.module file that shows the location of a MODULE.migrate.inc file, which contains all of the migrate hooks. This was implemented in migrate-1.0-beta4 and beyond.
hook_migrate_api()
<?php
/**
* Implementation of hook_migrate_api().
*/
function MYMODULE_migrate_api() {
$api = array(
'api' => 1,
'integration modules' => array(
'MYMODULE' => array('status' => FALSE),
),
);
return $api;
}
?>Migrate Hooks
All of these hooks should be placed inside the MYMODULE.migrate.inc
hook_migrate_types().
To add a new destination type. If you are just adding fields to users or nodes, then you don't need this.
<?php
/**
* Implementation of hook_migrate_types().
*/
function location_migrate_types() {
$types = array('location' => t('Node Location'));
return $types;
}
?>HOOKS BELOW MAY BE OUT OF DATE, AND NEED TO BE COMPLETED as of 2010/06/10
Migrate hook functions can be created to run custom code during the migration process. They can be created similar to the hook_migrate_init() example below, where the "examplemodule" would be the name of your module. See drupal hook documentation for more information on hooks.
<?php
/**
* Implementation of hook_migrate_init().
* parameters: none
* return: none
*/
function examplemodule_migrate_init() {
// do something the first time migrate_invoke_all() is called.
//return an array of settings
$settings = array(
//add a new destination
'destination' => array('examplemodule_destination' => t('My Destination'))
);
}
?>General Structure
The function migrate_invoke_all($kind, $hook, $type = NULL) is a general function that runs all module implementations of a particular hook and then returns an array of results from all those calls. Migrate hook functions have the general structure:
hook_migrate_KIND_HOOK()
or
hook_migrate_KIND_HOOK_TYPE
User Destination Hooks
Note: "destination" has been stripped from hook and function names, for more information see - #552928 - Strip "destination" from hook and function names
hook_migrate_fields_user($type)
returns an array of fields, which can be different on the user type (user role).
params: $type is the locatl role id (rid:int) of the role chosen for "Destination content type:" in the content set admin area.
returns: an array of fields used in the user destination
Examples (new):
<?php
function user_migrate_fields_user($type) {
$fields = array(
'uid' => t('User: Existing user ID'),
'name' => t('User: Username'),
'pass' => t('User: Password'),
'mail' => t('User: Email address'),
'created' => t('User: Account created'),
'access' => t('User: Account last accessed'),
'login' => t('User: Last logged in'),
'roles' => t('User: Roles'),
'status' => t('User: Status'),
);
return $fields;
}
?><?php
function profile_migrate_fields_user($type) {
$fields = array();
$profile = db_query("SELECT title, name FROM {profile_fields}");
while ($field = db_fetch_object($profile)) {
$fields[$field->name] = t('Profile: @title', array('@title' => $field->title));
}
return $fields;
}
?>hook_migrate_delete_user($uid)
params: $uid is the uid of the user being deleted
return: none
Example:
<?php
function user_migrate_delete_user($uid) {
timer_start('user_delete');
user_delete(array(), $uid);
timer_stop('user_delete');
}
?>hook_migrate_import_user($tblinfo, $row)
the main user import hook that runs code necessary to save import data in $row to a destination. The main implementation is user_migrate_import_user($tblinfo, $row)
params:
- $tblinfo contains table information, like field names
- $row an array of row values for user fields.
return: none
Example (simplified):
<?php
function user_migrate_import_user($tblinfo, $row) {
$sourcekey = $tblinfo->sourcekey;
// Begin building user object...
$newuser = array();
// Handle an update operation
if ($row->destid) {
$newuser['uid'] = $row->destid;
}
// If a uid was provided via mapping, load the existing user
else if (isset($tblinfo->fields['uid'])) {
$uidname = $tblinfo->fields['uid']['srcfield'];
$newuser = (array)user_load($row->$uidname);
// The existing md5 password will have another md5 applied to it if
// we're not careful - save it here and reset it later if no one else
// has set a password
$original_password = $newuser['pass'];
}
// Data which might be useful for user hooks.
$newuser['migrate_tblinfo'] = $tblinfo;
foreach ($tblinfo->fields as $destfield => $values) {
// Ignore CCK fields - we assume another module such as content_profile will deal with them
if (!preg_match('/^field_/', $destfield)) {
if ($values['srcfield'] && isset($row->$values['srcfield'])) {
$newvalue = $row->$values['srcfield'];
}
else {
$newvalue = $values['default_value'];
}
// ... code omitted: timestamp and role fields
$newuser[$destfield] = $newvalue;
}
}
// Prepare the user for import.
$errors = migrate_destination_invoke_all('prepare_user', $newuser, $tblinfo, $row);
// ... code omitted: handle errors from prepare_user
// ... code omitted: set field defaults if still unset
$account = user_save((object)$newuser, $newuser);
// Call completion hooks, for any processing which needs to be done after user_save
$errors = array_merge($errors, migrate_destination_invoke_all('complete_user', $account, $tblinfo, $row));
// ... code omitted: see actual module code for advanced usage...
}
?>Since the imported data is a user, user_save() is called to save the user data. hook_migrate_prepare_user() is called right before user_save() giving hooks a chance to change the user object before saving. Note: old implementation included a lot of extra stuff like content_profile integration that has been moved into profile.migrate.inc.
hook_migrate_prepare_user(&$user, $tblinfo, $row)
[need more info]
hook_migrate_complete_user(&$user, $tblinfo, $row)
[need more info]
Node Destination Hooks
hook_migrate_complete_node(&$node, $tblinfo, $row)
[need more info]
Miscellaneous Hooks
hook_migrate_global($type, $globals)
[need more info]
hook_migrate_init()
params: none
return: array of settings (destinations)
Example:
<?php
function migrate_migrate_init() {
$path = drupal_get_path('module', 'migrate') . '/migrate_destinations.inc';
include_once($path);
return array(
'destination' => array(
'comment' => t('Comment'),
'node' => t('Node'),
'user' => t('User'),
),
);
}
?>hook_migrate_destination_types()
returns what types are available for each destination.
params: none
return: types - an array in the form array( '[destination]' => array('[type_id]' =>'[type_name]'))
Example:
<?php
function migrate_migrate_destination_types() {
static $nodetypes = NULL;
if (!isset($nodetypes)) {
$nodetypes = array();
foreach (node_get_types() as $type => $info) {
$nodetypes[$type] = $info->name;
}
asort($nodetypes);
}
$types = array(
'comment' => array('comment' => t('Comment')),
'node' => $nodetypes,
'user' => user_roles(TRUE),
);
return $types;
}
?>