Desde que Migrate apareció en la estela de Drupal, las migraciones han pasado de ser uno de los mayores tormentos para un desarrollador, a ser una tarea interesante y hasta divertida (y sin estrés). En esta sesión nos meteremos de cabeza en la API de Migrate para ver cómo funciona, qué debemos tener en cuenta, cómo debemos preparar las fuentes de datos, y sobretodo, cómo gestionarlo dentro del ciclo de desarrollo del proyecto.
Pero... es Migrate un módulo sólo para migrar contenido? NO. Expondremos el cómo Migrate es un MUST en cualquier desarrollo, cómo nos puede ayudar a tener un conjunto de pruebas para nuestro site, cómo esto se integra en un proceso de desarrollo colaborativo y junto a un sistema de integración contínua.
3. Índice
01. Migración en Drupal
02. Conceptos básicos
03. Creación de una migración
04. Típicas situaciones en migraciones
05. Migrate en nuestro proceso de desarrollo
06. Migrate cómo framework
5. Migración en Drupal (I)
●
A la hora de enfocar un proyecto de migración en
Drupal hay 3 grandes soluciones:
–
By hand
–
Scripts personalizados
–
Feeds
–
Migrate
6. Migración en Drupal (II)
●
By Hand
–
–
●
Una locura: mucho tiempo y “muy” caro
(Quien piense en un becario su karma se verá reducido a menos
infinito)
Scripts personalizados
–
Tan flexible cómo quieras
–
Tienes que picarlo todo
–
No está integrado con lógica Drupal y menos aún con Drupal
–
Tracking? Rollback?
7. Migración en Drupal (III)
●
Feeds
–
Buena opción y muy bien documentado
–
Fácil de configurar y con soporte a distintos formatos
(RSS, Atom, CSV, base de datos, etc.)
–
Permite el mapeo de campos
–
Problemas con el rendimiento
–
Falta de integración con Drush
–
No funciona muy bien con las referencias a otros tipos
de contenidos
8. Migración en Drupal (y IV)
●
Migrate
–
Framework orientado a objetos para entrar contenidos a
Drupal
–
Fuente de datos diversa: CSV, DB, XML, JSON, etc.
–
Soporte para migrar a distintos tipos de contenido:
●
Nodo, usuario... cualquier entidad del core
●
Puedes definir tu própio handler (Media, Commerce, etc)
–
Rápido
–
Integración con Drush
–
Curva de aprendizaje: debemos programarlo todo.
10. Conceptos en Migrate
●
Antes de empezar, hay que dejar claros algunos conceptos
del día a día en una migración (y de Migrate):
–
Origen de datos
–
Destino de datos
–
Mapeo Origen-Destino
–
Mapeo de campos
–
Field handler
–
Destination handler
11. Origen de datos
●
Es el conjunto de datos desde dónde migraremos
●
Puede provenir de diversos tipos de fuente
$this->source = new MigrateSourceSQL($query);
12. Destino de datos
●
●
●
Es el lugar dónde se almacenarán los datos
migrados.
Esto puede ser una entidad (nodo, usuario, etc.) o
una tabla específica.
Cada registro de los datos de origen corresponde
con un registro de los datos de destino.
$this->destination = new
MigrateDestinationNode('migrate_example_beer');
13. Mapeo Origen-Destino
●
●
●
Establece una relación entre los ids del origen y los del destino.
Esto permite poder volver a ejecutar migraciones, ir hacia atrás,
actualizar registros, borrarlos y lo más importante....
Permite gestionar referencias de este contenido en otras migraciones.
$this->map = new MigrateSQLMap($this->machineName,
array(
'bid' => array(
'type' => 'int',
'not null' => TRUE,
)
),
MigrateDestinationNode::getKeySchema()
);
14. Mapeo de campos
●
Hace falta mapear el campo origen al campo destino.
●
Multitud de posibilidades.
$this->addFieldMapping('body', 'text');
$this->addFieldMapping('body:summary', 'excerpt');
$this->addFieldMapping('field_favbeers', 'beers')
->separator('|');
$this->addFieldMapping('title', 'name')
->defaultValue('Testing title');
$this->addFieldMapping('uid', 'accountid')
->sourceMigration('WineUser')
->defaultValue(1);
15. Field handler
●
Transforma los datos orígen en el formato/estructura que Drupal
entiende (basado en el tipo de campo). De:
$row->bar = array('foo', 'bar')
a algo más comprensible por Drupal:
$entity_field_bar = array(
'und' => array(
0 => array('value' => 'foo'),
1 => array('value' => 'bar'),
),
);
●
Ej. MigrateAddressFieldHandler, MigrateGeoFieldHandler
16. Destination handler
●
●
●
Se encarga de gestionar los datos procesados y
guardarlos en la entidad correspondiente.
Permite además, extender las destinaciones
existentes en el núcleo para añadir funcionalidad
extra
Ej. MigratePathautoHandler,
MigrateExtrasFlagHandler
17. Migrate extras
●
●
●
Este módulo extiende Migrate para añadir soporte
para diversos módulos contribuidos.
Añade soporte para migrar: Address Field, Entity
API, Flag, Media, etc.
En la página del módulo se puede consultar el
listado de módulos soportados y el estado de las
peticiones de soporte de otros módulos.
19. Pasos a seguir
1. Crear un módulo custom (con dependencia de Migrate). Por
ejemplo: migrate_myproject
2. Comunicar a Migrate que existimos (hook)
3. Crear una clase por cada migración y:
1. Añadir información sobre el origen de datos
2. Añadir información sobre el destino de los datos
3. Mapear el origen y el destino
4. Mapear los campos origen y destino.
5. De forma opcional, manipular los campos antes de guardarlos.
4. Registrar la clase de migración en el fichero .info del módulo
20. Crear módulo y hook
●
●
El fichero .module estará en blanco
Debemos crear un fichero llamado migrate_myproject.migrate.inc y
llamar al hook
function migrate_myproject_migrate_api() {
$api = array(
'api' => 2,
'groups' => array(
'fruits' => array(
'title' => t('Fruits'),
),
),
'migrations' => array(
'Apple' => array('class_name' => 'AppleMigration',
'group_name' => 'fruits'),
)
);
return $api;
}
21. Una clase = una migración
Class AppleMigration extend Migration {...}
●
●
Toda la lógica de migración la deberemos hacer
en el contructor de esta (método __construct).
Existen tres métodos opcionales que nos permiten
manipular los datos:
–
prepareRow($row)
–
prepare($entity, $row)
–
complete($entity, $row)
22. Flujo de la importación
●
●
●
●
●
●
Migrate itera en el origen de datos
Llama a prepareRow($row) permitiéndonos modificar los
datos o rechazarlos.
Migrate aplica los handlers y transforma $row en $entity
Llama a prepare($row, $entity) para poder modificar la
entidad antes de salvarla.
Se guarda la entidad.
Migrate setea el ID de la entidad y llama a complete($row,
$entity) para poder trabajar con él.
23. Implementación (I)
●
Especificar el origen, el destino, el mapeo origen-destino y
el mapeo de campos cómo hemos visto anteriormente.
class AppleMigration extends Migration {
public function __construct() {
parent::__construct();
$this->source = <my_source>;
$this->destination = <my_destination>;
$this->map = <my_map>;
$this->addFieldMapping($dst_field,
$src_field);
}
}
24. Implementación (II)
prepareRow($row)
●
●
Recibe un objeto que es un registro orígen a
migrar.
Nos permite hacer modificaciones o devolver
FALSE si no queremos migrar el registro.
$row->name = $row->name . ' ' . $row->surname;
$row->created = strtotime($row->init);
25. Implementación (III)
prepare($row, $entity)
●
●
●
Permite trabajar con la entidad por Migrate creada a partir
de los datos origen antes de salvarla.
Hemos de tener en cuenta que los datos modificados en
$entity deben tener el formato del campo de la entidad.
Se puede usar este método para añadir valores a campos
que no tienen handler.
$entity->field_link['und'][0]['value'] =
'http://drupal.org/project/migrate';
26. Implementación (y IV)
complete($row, $entity)
●
●
Se llama justo después de haber guardado la
entidad (ya tenemos disponible el ID).
Se puede usar para crear otras entidades que
necesiten esta información.
27. Registro en el .info
●
Todos los ficheros con clases de migración deben
estar listados en el fichero .info (típico error)
name = MyProject Migrate
description = ...
dependencies[] = migrate
files[] = apple.inc
28. Lanzar migraciones (I)
●
●
●
●
●
Se puede lanzar las migraciones desde la UI.
Es fácil, intuitivo y nos da información en todo
momento.
Pero un poco lento...
Si hemos programado todo esto, no nos vamos a
pasar a la UI, no?
A los devs nos gusta drush!
29. Lanzar migraciones (II)
drush migrate-status
drush migrate-import Apple
drush migrate-import Apple –limit=”10 seconds”
drush migrate-import Apple –feedback=”10 items”
drush migrate-rollback Apple
drush migrate-rollback Apple –idlist=4,9
●
Y muchos más...
31. Conexión a BD antigua
●
Es normal que el proyecto conste de migrar desde
una base de datos antigua.
$query = Database::getConnection('default',
'for_migration')
->select('tags', 't')
->fields('t', array('id_tag', 'tag'));
$this->source = new MigrateSourceSQL($query);
32. Migración de imágenes embebidas
●
●
Puede ser que queramos migrar estas imágenes a
entidades de Media.
El módulo Migrate Extras nos da soporte para
migrar este tipo de entidades y además nos da
una función muy útil.
public function prepare($node, $row) {
MigrateDestinationMedia::rewriteImgTags
($node, $field_text);
}
33. Redirecciones en URLs antiguas
●
●
Un requerimiento típico en migraciones es la
conservación de las URLs antiguas a través de
redirecciones.
Migrate nos da soporte para poder hacer esto a
través de un parche.
$this->addFieldMapping('migrate_redirects',
'old_legacy_path');
35. Generar contenido de prueba (I)
●
●
●
●
●
Quién no ha pasado horas metiendo contenido de
prueba en un proyecto?
Y cuando haces una modificación, quién se encarga
de meter contenido de pruebas?
Y si trabajamos en distintos entornos? (dev, staging,
pre)
Siempre pasa que las pruebas de contenido no se
van haciendo...
Y si pudiésemos hacerlo de forma automática?
36. Generar contenido de prueba (II)
●
●
●
●
Crear CSVs con contenidos de pruebas para Nodos,
términos, usuarios, enlaces de menú, imágenes, etc.
Crear unos pequeños scripts para importar el contenido.
Y todo esto se hace una vez y ya lo podemos usar para
todos nuestros proyectos y entornos.
Podemos programar pruebas a partir de esto de forma
automatizada, integrarlo con nuestro Jenkins, etc.
38. Migrate sobre migrate
●
Se han creado módulos sobre Migrate para
migraciones específicas:
–
Drupal-to-Drupal data migration
–
WordPress Migrate
–
Commerce Migrate
–
TYPO3 migrate
–
phpBB2Drupal