Plugin Migrations : collaborez et déployez simplement vos applications CakePHP !

Je vous propose aujourd’hui une introduction au nouveau plugin de migrations pour CakePHP qui vient d’être rendu open source par CakeDC (mon entreprise). Le but est d’expliquer en quelques lignes le fonctionnement du plugin (vraiment simple) et l’intérêt d’utiliser les migrations au sein de vos applications.

Description du plugin en une phrase : il permet aux développeurs de versionner et d’automatiser la création / mise à jour du schéma de la base de données d’une application ainsi que de ces données depuis la ligne de commande.

Pour information, cela fait plusieurs années que le plugin est utilisé en interne chez CakeDC sur tous les projets afin de faciliter le travail en équipe et le déploiement des applications … Il a récemment été totalement ré-écrit et testé pour une ouverture en open source (licence MIT), et est désormais disponible (ainsi que sa documentation) gratuitement !

En quoi est-ce utile ?

Cela fait déjà un bon moment que l’utilisation de logiciels de version de code tels que CVS, SVN, Mercurial ou Git est incontournable au sein des entreprises. Même lorsque l’on développe seul, cette pratique est largement conseillée … et il est difficile de faire sans lorsque l’on en a pris l’habitude.

Une application est totalement dépendante du schéma de la base de données sur laquelle elle est censée tourner, malheureusement il n’est pas très simple de versionner cette partie d’une application. Plusieurs solutions existent comme les fichiers SQL purs ou l’utilisation du shell Schema de CakePHP (j’en avais déjà parlé ici) … mais aucune n’est suffisamment simple ni aboutie pour être utilisée convenablement.

D’autre part, le développement d’une application ne s’arrête jamais (entre les mises à jour, corrections de bugs, ajouts de fonctionnalités …) et il faut trouver des solutions pour facilement mettre en ligne les modifications effectuées. Les techniques de déploiements sont très variées, cela va du remplacement des fichiers avec un client FTP et la mise à jour de la base de données avec un script SQL à la mise en place d’un système automatisé avec des outils tels que Capistrano.

Le plugin de Migrations fournit un moyen simple de versionner la base de données. Il permet :

• de connaître à tout moment quel doit être le schéma de la base de données : il suffit d’appliquer toutes les migrations sur une base de données vide pour avoir un schéma à jour
• de faciliter le travail en équipe : lorsqu’un développeur récupère les mises à jour du code il peut mettre à jour sa base de données en une seul ligne de commande. Tous les développeurs travaillent donc toujours avec le même schéma !
• de faciliter les mises à jour : le plugin connaît l’état de la base de données, et il est très simple de voir si celui-ci n’est pas à jour. Dans ce cas, il suffit d’appliquer les migrations nécessaires pour mettre le schéma à jour instantanément
• de ne pas manipuler que des schémas : un système de callbacks permet de faire tout ce que vous voulez lors d’une migration. Quelques exemples : créer un compte initial pour l’administrateur, ajouter des données initiales (comme la liste des catégories disponibles), modifier les valeurs déjà présentes dans la base. La seule limite est votre imagination !

Où trouver le code ?

Annoncé il y a quelques semaines, le plugin est accessible depuis la nouvelle section « Downloads » de CakeDC.com. Cette page contient un lien de téléchargement de la version 1.0, la documentation du plugin ainsi que l’adresse du projet sur Codaset (équivalent de Github) pour les tickets et l’accès Git.

Afin de sensibiliser les utilisateurs sur l’importance de faire un don à la Cake Software Foundation pour soutenir le projet CakePHP (c’est malheureusement assez rare) le plugin n’était accessible qu’aux donateurs durant les premières semaines. Ce week-end un bouton « Download without donation » a été ajouté … ce qui ne vous empêche pas de contribuer à la campagne de donation de CakePHP si vous appréciez le framework :

Encore mieux ! Une application simple d’exemple est disponible pour ceux qui veulent voir comment intégrer le plugin de migrations et un exemple concret d’utilisation. Téléchargez le code, ou bien clonez le projet avec Git :

git clone git://codaset.com/cakedc/sample-migrations-application.git sample_migrations

Il vous suffit ensuite de créer un fichier de configuration pour votre base de données, et d’indiquer l’emplacement du coeur de CakePHP.

Pour les utilisateurs de Git, faites également

git submodule init
git submodule update

pour ajouter le plugin de migrations automatiquement !

Ajouter le plugin à une application

Note : la version proposée au téléchargement est faite pour CakePHP 1.3. Il est donc recommandé d’utiliser la version 1.3-beta du framework.

L’ajout du plugin dans une application existante, est très simple.

Si vous avez téléchargé une archive contenant le code, placez le contenu dans le dossier « /plugins/migrations » de votre application. Pour ceux qui préfèrent Git, ajoutez le plugin en sous module :

git submodule add git://codaset.com/cakedc/migrations.git plugins/migrations

Pour vérifier que cela fonctionne, il suffit de taper la ligne de commande ci-dessous depuis la racine de votre application pour voir apparaître les commandes disponibles :

cake migration help

Si vous avez un problème à ce niveau, référez vous à la documentation du framework sur l’utilisation de la console.

Utilisation du plugin

Je ne vais pas faire un tutorial complet sur l’utilisation du plugin, mais seulement présenter quelques commandes utiles et des cas d’utilisation. Si vous souhaitez une documentation exhaustive je vous invite à parcourir la documentation officielle (en anglais) mise à disposition par CakeDC.

Pour un cas d’utilisation simpliste mais utile pour la compréhension, je vous recommande fortement de regarder l’application de test mise à disposition. L’analyse de l’historique et des commits permet de facilement comprendre comment utiliser les migrations dans un processus de développement.

Créer une migration

Pour créer une migration il suffit de taper

cake migration generate

L’outil vous demandera de lui donner un nom, et vous proposera de faire un dump de la base de données. Si un fichier « schema.php » existe dans votre application, vous pourrez générer une migration contenant les instructions nécessaires à la migration du schéma décrit dans schema.php vers le schéma actuel de votre base.

Les migrations générées sont ajoutées au dossier « /config/migrations » de votre application.

Appliquer / Annuler des migrations

Lorsque vous récupérer une application contenant des migrations, différentes commandes sont à votre disposition pour appliquer ou annuler des migrations.

cake migration

C’est la commande la plus simple. Elle va afficher la liste des migrations trouvées dans l’application ainsi que leur statut (appliquée ou non). Chacune étant numérotée, il vous suffit de taper le numéro de la migration représentant l’état de la base de données que vous souhaitez obtenir.

Pour aller encore plus vite, vous pouvez utiliser les commandes : cake migration up, down, all ou reset. Elles vous permettront respectivement :

• d’appliquer la prochaine migration
• d’annuler la dernière migration appliquée
• d’appliquer toutes les migrations non appliquées (pour obtenir la dernière version du schéma de la base de données)
• d’annuler toutes les migrations appliquées (pour obtenir une base de données vides)

Migrations pour des plugins

L’ajout de plugins à une application CakePHP nécessite souvent la création de nouvelles tables dans la base de données. Le plugin de migrations permet aux développeurs d’ajouter les migrations nécessaires à leurs plugins, et aux utilisateurs de les appliquer tout aussi simplement.

La seule différence par rapport aux commandes présentées ci-dessus est l’ajout du paramètre « -plugin nomduplugin » à la commande. Par exemple, imaginons que le plugin de formulaire de contact proposé sur Formation-cakephp.com (un peu de publicité pour les copains ) veuille faciliter l’installation du plugin il suffira de générer des migrations avec :

cake migration generate -plugin contact

Pour rendre l’installation encore plus puissante il serait possible d’implémenter l’ajout des lignes de configuration nécessaires (email de destination des messages) au fichier « config/bootstrap.php » de l’application. C’est possible grâce au système de callbacks (que je ne détaillerai pas ici. Un exemple simple de création d’un compte administrateur est visible dans l’application de test).

Dans tous les cas, l’utilisateur final du plugin n’aura qu’une seule commande à taper lors de l’installation :

cake migration run all -plugin contact

Note : le « run » de la commande ci-dessus n’est pas obligatoire, c’est elle qui est appelée lorsque l’on exécute « all » tout seul.

Pour aller plus loin

Il y a différentes manières d’utiliser les migrations au sein de vos applications et je vous invite à donner des exemples d’utilisation que vous jugez intéressantes en commentaire de cet article.

Cet article n’est pas destiné à servir de lieu de support pour le plugin ! Je vous recommande donc d’utiliser les outils officiellement mis à votre disposition :

• Si vous trouvez un bug, ou avez des propositions d’amélioration : ouvrez un ticket !
• Une question sur l’utilisation, ou un problème d’installation : posez votre question à la communauté sur CakeQs ! Je passe plusieurs fois par jour là-bas et vous donnerai la réponse la plus précise possible pour vous aider.
• Une adaptation spécifique aux processus de votre entreprise, de la formation ou du support professionnel … contactez CakeDC (c’est notre métier)

Enfin, pour toute remarque n’hésitez pas à ajouter un commentaire, me contacter ou à me poser votre question.