Vous êtes ici

Aide à la migration automatisée d'un module Drupal 7 vers Drupal 8

Vous avez 30 secondes ?
S'abonner au flux d'actualités
Rubrique: 
Technique
Difficultée: 
Difficile
Dans ce tutoriel, nous allons apprendre à utiliser un script d'aide à la migration des modules Drupal 7 vers Drupal 8. Ce script est une aide : pas une migration complètement automatisée !
Contrairement à notre habitude, ce tutoriel ne s'adresse pas aux débutants mais aux développeurs de modules Drupal 7 souhaitant une aide à la migration de leur module Drupal 7 vers Drupal 8.
 
En tant que développeur, vous souhaitez porter votre module sur Drupal 8 : grand bien vous en fasse, mais ce n'est pas gagné ! En effet, vous vous apercevrez bien vite que, du fait changement de paradigme (passage de la programmation fonctionnelle à la programmation objet) ainsi que du fait des changements d'API et de librairies, énormément de choses ont changé entre Drupal 7 et Drupal 8. Basiquement, il vous faudra changer presque chaque ligne de code de votre module. Oui mais voilà : que changer, et comment ?
 
Une bonne solution pour le découvrir est de lire le changelog Drupal 8, c'est à dire la liste décrivant les changements intervenus entre Drupal 7 et Drupal 8, ainsi que la manière de les migrer.
Liste des changements intervenus entre Drupal 7 et 8 :
 
Cette liste est longue comme le bras et il est vite difficile de savoir quelle section est intéressante pour la migration de votre module. C'est là qu'intervient la méthode suivante qui vous permettra de vous assister dans votre migration, en fournissant l'ensemble des changements impactant votre module en particulier.
 
Drupal met à disposition des développeurs une liste de tous les changements intervenus entre Drupal 7 et Drupal 8 : https://www.drupal.org/list-changes.
Cette liste étant exhaustive et très longue, la méthode proposée dans cet article construit une documentation personnalisée des changements propres au module que vous cherchez à convertir.
Mieux encore, certaines conversions pourront être assistées !
 
Voici les étapes pour rendre cela possible :
  • Prérequis
    • Installation de Composer
    • Installation de Drush
    • Installation de Drupal 8
  • Réalisation
    • Installation de Drupal Module Upgrader
    • Réalisation d'un rapport d'analyse du code à convertir
    • Conversion automatique du code

Installation de Composer

Composer :
Composer est un outil de gestion de dépendances pour les projets PHP. Concrètement, mettons que vous souhaitiez installer une application écrite en PHP permettant l'envoi d'emails suivant votre planning. Cette application dépendra certainement d'une librairie de gestion des emails et d'une librairie de gestion de calendrier et il vous faudra installer ces deux outils prérequis. Cette dernière librairie gérant les calendriers pourrait elle-même nécessiter l'installation d'une tierce librairie de gestion de dates. Et ainsi de suite ! Composer adresse ce problème en installant pour vous l'ensemble de la chaîne des dépendances d'un projet. Plus d'infos ici !
 
L'installation de Composer s'effectue en suivant simplement les étapes de sa documentation :
Notez qu'un installeur Windows est disponible pour une installation simplifiée.
 
Une fois Composer installé, vous devriez être capable de lancer une fenêtre de commande et d'entrer la commande suivante qui devrait retourner une liste des commandes Composer disponibles :

composer

En cas d'erreur et si l'installation a semblé pourtant bien se dérouler, vérifiez que vous avez le chemin vers le dossier bin de votre installation Composer inclus dans votre PATH :
set PATH=%PATH%;C:\ProgramData\ComposerSetup\bin;

Installation de Drush

Drush :
Drush est un utilitaire en ligne de commande permettant l'administration rapide d'un site Drupal. Il permet, d'une simple commande, de télécharger Drupal, de l'installer, de télécharger des modules et de les activer. Il facilite également de nombreuses opérations de maintenance et permet la réalisation de scripts de déploiement et de gestion automatisée de votre site. Plus d'infos ici.
 
L'installation de Drush est décrite dans cette documentation pour chacun des systèmes d'exploitation:
Notez qu'un installeur Windows est disponible pour une installation simplifiée. Attention à bien lancer l'installation complète, incluant l'enregistrement des variables systèmes. Plus d'infos ici.
 
Après installation via le lien ci-dessus, ouvrez une fenêtre de commande et lancez :

drush status

Vous devriez voir alors apparaitre les informations suivantes :
PHP executable         :  php.exe
PHP configuration      :  C:\wamp\bin\php\php5.5.12\php.ini
PHP OS                 :  WINNT
Drush version          :  7.0-dev
Drush temp directory   :  C:\Utilisateurs\...\AppData\Local\Temp
Drush configuration    :
Drush alias files      :
En cas d'erreur, vérifiez que :

?set PATH "%PATH%;C:\ProgramData\Drush\;C:\Program Files (x86)\Drush\GnuWin32\bin;C:\Program Files (x86)\Drush\Php;C:\Program Files (x86)\Drush\cwRsync\bin;"

  • ?En cas de doute, référez-vous à la documentation complète.

Installation de Drupal 8

Référez-vous au tutoriel Drupal-Addict correspondant : Installer Drupal Core 8.x

Installation de Drupal Module Upgrader

1. Téléchargez le module Drupal Module Upgrader
Astuce :
Maintenant que vous avez Composer, vous pouvez simplement utiliser la commande suivante depuis la racine de votre installation Drupal 8 :

drush dl drupalmoduleupgrader

2. Décompressez ce module et placez-le dans le dossier /modules de votre installation Drupal 8
3. Lancez une console cmd dans le dossier de votre module
Astuce :
Sous Windows, effectuez SHIFT+clic sur le dossier du module puis ouvrir une invite de commande ici. Sinon utilisez la commande :

cd C:/wamp/www/drupal8/modules/drupalmoduleupgrader

4. Lancez l'intégration du module avec drush. Pour cela, utilisez la commande suivante depuis le dossier du module :

composer install

5. Activez le module Drupal Module Upgrader. Si vous n'êtes pas certains de la façon de faire, suivez notre tutoriel Installer et activer un module simple, méthode graphique
Astuce :
Maintenant que vous avez drush, vous pouvez simplement utiliser la commande suivante depuis la racine de votre installation Drupal :

drush en drupalmoduleupgrader -y

Réalisation d'un rapport d'analyse du code à convertir

Maintenant que tous nos outils sont installés, nous allons analyser notre module à convertir afin de générer une documentation personnalisée des changements à effectuer.
1. Placez le module à convertir dans le dossier /modules de votre installation Drupal 8. Comme il s'agit d'un module Drupal 7, celui ne sera bien entendu pas reconnu par Drupal.
2. Lançons l'analyse. Dans une fenêtre de commande, depuis la racine de votre site Drupal 8, lancez la commande suivante :

drush dmu-analyze MODULE_NAME

3. Ouvrez - avec votre navigateur préféré - le fichier upgrade-infos.html qui se trouve dans le dossier de votre module.
 
Le rapport généré contient des indications sur chaque point de conversion important. L'ensemble des points est trié par type (base de données, accès aux variables, fichier info, etc...). Pour chacun des points, nous retrouvons un lien vers la documentation complète indiquant comment en effectuer la conversion, ainsi que la liste des fichiers impactés (voire les lignes en question dans ces fichiers lorsque cela est possible).
 
Extrait du rapport de conversion du module Search Autocomplete.
Extrait du rapport de conversion du module Search Autocomplete.

Conversion automatique du code

Allons encore plus loin et demandons à Drupal Module Upgrader de convertir pour nous certaines sections de code.
La conversion effectuée est loin d'être parfaite. Dans la plupart des cas non triviaux la conversion n'est même pas fonctionnelle. Ne vous attendez pas à pouvoir lancer votre nouveau module Drupal 8 sans effort ! Le but ici est de vous avancer en pré-écrivant pour vous un maximum de code et en vous joignant les documentations nécessaires à votre travail.
1. Dans une fenêtre de commande placée à la racine de votre installation Drupal, lancez la commande :

drush dmu-upgrade MODULE_NAME

ou pour convertir tout en supprimant les anciens fichiers :

drush dmu-upgrade MODULE_NAME --clean

Le module converti apparaît désormais dans Drupal 8.
Le module converti apparaît désormais dans Drupal 8.
 
Votre nouveau module est désormais reconnu par Drupal 8 car dmu est capable de convertir correctement le .info. Toutefois, n'activez pas votre module sous peine de risquer un plantage complet de votre site Drupal 8, surtout si des erreurs sont apparues durant la conversion. Tout ceci n'est qu'une aide, et les fichiers générés doivent bien entendu être relus et vérifiés.
 
Notez que pour terminer la conversion de votre module, vous pouvez vous aider de notre série de tutoriaux : Créer un module Drupal 8.
 
En résumé...
 
Drupal Module Upgrader est un module s'intégrant avec l'outil en ligne de commande Drush et permettant d'assister le développeur dans la migration de son module Drupal 7 vers Drupal 8.
Une fois correctement installé, dmu (Drupal Module Upgrader) s'utilise en tant que commande drush :
  • drush dmu-analyze MODULE_NAME pour analyser les conversions à effectuer et générer une documentation d'aide personnalisée.
  • drush dmu-upgrade MODULE_NAME pour tenter une conversion automatique du module.
Notation: 
Average: 5 (1 vote)
Vous avez aimé: 

Commentaires

Là c'est un sujet touchy ! Je ne l'ai encore pas fait et ne m'y suis pas encore hyper intéressé. Pour deux raisons :
- Drupal 8 est en bêta seulement et les modules contributeurs ne sont encore majoritairement pas prêt. Utiliser Drupal 8 en production me semble donc encore trop ambitieux.
- Un process de migration "plus solide" que dans les précédentes version est en cours de travail, pour upgrader de Drupal 6 ou 7 à Drupal 8. J'avais vu passé une décision d'inclure ce process à Drupal 8.1.x, mais récemment un module Migrate Drupal est apparu dans les dernières bêta. Je ne sais pas encore ce qu'il vaut, je n'ai pas eu l'occasion de l'essayer.
Une UI est en cours, c'est un peu prêt tout ce que j'en sais !! (https://www.drupal.org/node/1886616)
 
En fait, ça me paraît encore un peu tôt pour voir tout ça de manière définitive ! D'autant que j'imagine que ceci ne va convertir que du Core vers le Core, mais il faudra attendre tous les modules contributeurs stables en D8 pour pouvoir les convertir également !
 
Voilà... je crois que n'ai pas avancé beaucoup le débat avec cette réponse ! Mais si d'autres ont d'autres infos, merci de partager ! ^^
This post is useful!
This post is useless!