Ecrire votre première migration Drupal

Dans le post précédent, nous avons appris que l’API Migrate est une implémentation d’un framework ETL. Nous avons également parlé des étapes de l’écriture et de la gestion des migrations. Maintenant, écrivons notre première migration Drupal. Nous allons commencer par un exemple très simple : créer des nœuds à partir de données codées en dur. Pour cela, nous supposons une installation Drupal utilisant le profil d’installation `standard’; qui est fourni avec le type de contenu `Basic Page’. Au fur et à mesure que nous progresserons dans la série, les migrations deviendront plus complètes et plus complexes. Idéalement, un seul concept sera introduit à la fois. Lorsque cela n’est pas possible, nous vous expliquerons comment les différentes parties fonctionnent ensemble. L’objectif de la leçon d’aujourd’hui est d’apprendre la structure d’un fichier de définition de migration et comment l’exécuter.

Rédiger le fichier de définition de la migration

Le fichier de définition de migration doit vivre dans un module. Donc, créons un module personnalisé nommé `ud_migrations_first’; et définissons le module `migrate’; du noyau Drupal comme dépendances dans le fichier *. info.yml.

Loading gist https://gist.github.com/dinarcon/1b64ad61969848b92a3c7ce305dcd7ea

Maintenant, créons un dossier appelé `migrations’; et à l’intérieur un fichier appelé `udm_first.yml`. Notez que l’extension est `yml`, pas `yaml`. Le contenu du fichier sera :

Loading gist https://gist.github.com/dinarcon/1b64ad61969848b92a3c7ce305dcd7ea

La structure finale du dossier ressemblera à:

.
|-- core
|-- index.php
|-- modules
|   `-- custom
|       `-- ud_migrations_first
|           |-- migrations
|           |   `-- udm_first.yml
|           `-- ud_migrations_first.info.yml

YAML est un format de valeur clé avec imbrication optionnelle d’éléments. Ils sont très sensibles aux espaces blancs et aux indentations. Par exemple, ils ont besoin d’au moins un espace après le symbole deux-points (:) qui sépare la clé de la valeur. Notez également que chaque niveau de la hiérarchie est indenté par deux espaces exactement. Une source commune d’erreurs lors de l’écriture de migrations est un espacement ou une indentation incorrecte des fichiers YAML.

Un rapide coup d’œil au fichier révèle les trois parties principales : source, processus et destination. D’autres clés fournissent des informations supplémentaires sur la migration. Il y a d’autres clés que celles montrées ci-dessus. Par exemple, il est possible de définir des dépendances entre les migrations. Une autre option est de baliser les migrations pour qu’elles puissent être exécutées ensemble. Nous en apprendrons plus sur ces options dans les prochains articles.

Examinons chaque paire clé-valeur du fichier. Pour `id`, il est d’usage de définir sa valeur pour correspondre au nom du fichier contenant la définition de migration, mais sans l’extension `. yml`. Cette clé sert d’identifiant interne que Drupal et l’API Migrate utilisent pour exécuter et suivre la migration. La valeur `id` doit être composée de caractères alphanumériques, en utilisant éventuellement des traits de soulignement pour séparer les mots. Quant à la clé `label`, c’est une chaîne lisible par l’homme utilisée pour nommer la migration dans différentes interfaces.

Dans cet exemple, nous utilisons le plugin source `embedded_data`. Il permet de définir les données à migrer directement dans le fichier de définition. Pour le configurer, vous définissez une clé `data_rows` dont la valeur est un tableau de tous les éléments que vous voulez migrer. Chaque élément peut contenir un nombre arbitraire de paires clé-valeur représentant des `colonnes` de données à importer.

Un cas d’utilisation courant pour le plugin `embedded_data` est de tester l’API Migrate elle-même. Une autre méthode valable consiste à créer un contenu par défaut lorsque les données sont connues à l’avance. Je présente souvent des ateliers d’introduction à Drupal. Pour gagner du temps, j’utilise ce plugin pour créer des nœuds qui seront utilisés plus tard dans l’explication de création de vues. Consultez ce référentiel pour un exemple de cela. Notez qu’il utilise une structure de répertoires différente pour définir les migrations. Cela sera expliqué dans les prochains billets de blog.

Pour la destination nous utilisons le plugin `entity:node` qui vous permet de créer des noeuds de tout type de contenu. La clé `default_bundle` indique que tous les nœuds à créer seront de type `Basic page`, par défaut. Il est important de noter que la valeur de la clé `default_bundle` est le nom de machine du type de contenu. Vous pouvez le trouver dans `/admin/structure/types/manage/page`. En général, l’API Migrate utilise les noms de machine pour les valeurs. Au fur et à mesure que nous explorerons le système, nous indiquerons quand ils seront utilisés et où trouver les bons.

Dans la section processus, vous mappez les colonnes de la source aux propriétés et aux champs des nœuds. Les clés sont des noms de propriétés d’entités ou des noms de machines de champs. Dans ce cas, nous définissons des valeurs pour le `titre` du noeud et son champ `body`. Vous pouvez trouver les noms des machines de champ dans la page de configuration du type de contenu : `/admin/structure/structure/types/manage/page/page/champs`. Les valeurs peuvent être copiées directement de la source ou transformées via des plugins de processus. Cet exemple fait une copie mot à mot des valeurs de la source à la destination. Les noms de colonnes dans la source ne doivent pas nécessairement correspondre à la propriété de destination ou au nom de champ. Dans cet exemple, ils sont différents pour faciliter leur identification.

Vous pouvez télécharger le code de l’exemple à partir de https://github.com/dinarcon/ud_migrations. L’exemple ci-dessus se trouve en fait dans un sous-module de ce référentiel. Le même référentiel sera utilisé pour de nombreux exemples tout au long de la série. Téléchargez tout le référentiel dans le répertoire `.modules/custom` de l’installation de Drupal et activez le module `UD First Migration`.

Exécution de la migration

Utilisons Drush pour exécuter les migrations avec les commandes fournies par Migrate Run. Ouvrez un terminal, basculez les répertoires sur la racine Web de Drupal, et exécutez les commandes suivantes.

$ drush pm:enable -y migrate migrate_run ud_migrations_first
$ drush migrate:status
$ drush migrate:import udm_first

La première commande active le module de migration du noyau, le runner et le module personnalisé contenant le fichier de définition de migration. La deuxième commande affiche une liste de toutes les migrations disponibles dans le système. Un seul devrait être listé avec l’ID de migration `udm_first`. La troisième commande exécute la migration. Si tout se passe bien, vous pouvez visiter la page d’aperçu du contenu dans /admin/content et voir les deux pages de base créées. Félicitations, vous avez réussi votre première migration Drupal!!!

Ou peut-être pas ? Les migrations Drupal peuvent échouer de plusieurs façons et parfois les messages d’erreur ne sont pas très descriptifs. Dans les prochains billets de blog, nous parlerons des flux de travail recommandés et des stratégies pour déboguer les migrations. Pour l’instant, mentionnons quelques-unes des choses qui pourraient mal tourner dans cet exemple. Si après avoir lancé la commande `drush migrate:status’; vous ne voyez pas la migration `udm_first`, assurez-vous que le module `ud_migrations_first` est activé. Si elle est activée, et que vous ne la voyez pas, reconstruisez le cache en exécutant `drush cache:rebuild`.

Si vous voyez la migration, mais vous obtenez une erreur d’analyse yaml lors de l’exécution de la commande `migrate:import`, vérifiez votre indentation. Copier et coller de GitHub vers votre IDE/éditeur peut changer l’espacement. Un espace étranger peut briser toute la migration, alors soyez très attentif. Si la commande signale qu’elle a créé les nœuds, mais que vous obtenez une erreur fatale en essayant d’en visualiser un, c’est que le type de contenu n’a pas été correctement défini. Rappelez-vous que le nom de machine du type de contenu `Basic page` est `page` et non `basic_page`. Cette erreur ne peut pas être corrigée à partir de l’interface d’administration. Ce que vous devez faire, c’est annuler la migration en émettant la commande suivante : Drush migrate:rollback udm_first`, puis fixez la valeur `default_bundle`, reconstruisez le cache, et importez à nouveau.

Remarque: Migrate Tools peut être utilisé pour exécuter la migration. Ce module dépend de Migrate Plus. Pour l’instant, limitons au minimum les dépendances des modules pour se concentrer sur les fonctionnalités de base de Migrate. De plus, le fait de les ignorer démontre que ces modules, bien qu’ils soient très utiles, ne sont pas des exigences strictes pour la gestion de projets de migration. Si vous décidez d’utiliser Migrate Tools, assurez-vous de désinstaller Migrate Run. Les deux fournissent les mêmes commandes de Drush et sont en conflit l’une avec l’autre si les deux sont activées.

Qu’avez-vous appris dans le billet d’aujourd’hui ? Saviez-vous que Migrate Plus et Migrate Tools ne sont pas des exigences strictes pour les projets de migration Drupal ? Saviez-vous que vous pouvez placer vos fichiers YAML dans un répertoire `migrations’; ? Quel conseil donneriez-vous à quelqu’un qui écrit sa première migration ? Veuillez partager vos réponses dans les commentaires. Aussi, je vous serais reconnaissant de bien vouloir partager ce billet de blog avec vos amis et collègues.