Migrate, una herramienta de trabajo y desarrollo

Migrate, una herramienta de trabajo y desarrollo

Ramon Vilar

Sobre mi

Ramon Vilar

ramon@ymbra.com

@rvilar

Í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

MIGRACIÓN EN DRUPAL

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

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?

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

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.

CONCEPTOS BÁSICOS

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

Origen de datos

● Es el conjunto de datos desde dónde migraremos● Puede provenir de diversos tipos de fuente

$this->source = new MigrateSourceSQL($query);

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

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

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

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

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

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.

CREACIÓN DE UNA MIGRACIÓN

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

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

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)

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.

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

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

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

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.

Registro en el .info

● Todos los ficheros con clases de migración deben estar listados en el fichero .info (típico error)

name = MyProject Migratedescription = ...dependencies[] = migrate

files[] = apple.inc

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!

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

TÍPICAS SITUACIONES EN MIGRACIONES

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

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

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

MIGRATE EN NUESTRO PROCESO DE DESARROLLO: CONTENIDO DE PRUEBA

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?

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.

MIGRATE CÓMO FRAMEWORK

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

Contacto

● Twitter: @rvilar● Correo: ramon@ymbra.com● Web: http://ymbra.com● Grácias a todos(as) ¿Preguntas?