Le plugin Migrations de CakePHP, un indispensable !

4 octobre 2013
Aymeric

Si vous êtes développeur CakePHP et que vous n'utilisez pas le plugin Migrations alors je vous invite à lire cet article. Le plugin Migrations est tout simplement indispensable !

Késako ?

Le plugin Migrations à pour objectif de vous permettre de "versionner" votre structure de base de données.

Prenons un exemple très simple. Vous avez un site en production avec une base de données. Dans cette base de données vous avez des tables. Tout marche correctement dans le meilleur des mondes.

Imaginons maintenant que la structure d'une table change (ajout ou suppression d'un champs). Lors de la mise en prod il faudra effectuer cette modification dans la base de données à la main... Pas cool !

Prenons un autre exemple plus complexe. Vous souhaitez ajouter un champs à une table et remplir ce champs en fonction d'un autre champs pour toutes les entrées de la table ! Encore moins cool !

Le plugin Migrations permet de régler ces problèmes et nous allons voir comment.

Installation du plugin

Le plugin est disponible sur github à l'adresse suivante : https://github.com/CakeDC/migrations.

La première étape est donc de récupérer le plugin et de l'installer dans votre application CakePHP. Pour cela vous avez plusieurs solutions :

  • Vous copier les sources dans un dossier "Migrations" dans le dossier plugin de votre application
  • Si vous utilisez git vous pouvez l'ajouter en sous-module avec la commande suivante :
  • En utilisant composer donc une doc est dispo ici : http://getcomposer.org/

Ci-dessous la commande pour ajouter le plugin en sous-module : 

git submodule add git://github.com/CakeDC/migrations.git Plugin/Migrations
git submodule update --init --recursive

La deuxième étape est de charger le plugin dans votre projet CakePHP. Pour cela il faut ajouter la ligne suivante dans votre fichier Config/bootstrap.php : 

CakePlugin::load('Migrations', array('bootstrap' => true, 'routes' => true));

Vous êtes maintenant fin près à utiliser le plugin Migrations de CakePHP pour vous simplifier la vie.

Générer une "Migrations" simple

L'utilisation du plugin Migrations se fait exclusivement en ligne de commande. Pour ceux que ça intéresse le plugin Migrations a été intégré dans l'espace administration de Croogo disponible sur github ici .

Vous allez donc devoir utiliser la console de CakePHP pour générer vos migrations. Pour ce tutorial nous allons considérer que vous avez ajouté le chemin du dossier lib/Cake/Console dans votre variable d'environnement \$PATH. Cela permettra d’appeler le scipt "cake" de partout dans votre console.

Pour générer vos migrations le plugin va utiliser les modèles de votre application. Je vous conseil donc de créer un modèle pour chaque table de votre application. C'est une bonne pratique à avoir.

Ensuite il suffit d’exécuter la commande suivante : 

cake Migrations.Migration generate

Si vous souhaitez générer les migrations d'un plugin il faut ajouter l'option -p pluginName : 

cake Migrations.Migration generate -p pluginName

Les questions suivantes vont vous être posées :

  • Do you want generate a dump from current database? Il faut répondre oui
  • Do you want to preview the file before generation? Répondre oui pour prévisualiser la migration dans la console
  • Please enter the descriptive name of the migration to generate: Donnez un nom à votre migration. Vous pouvez mettre des espaces. Évitez les caractère spéciaux, cette description est utilisée comme nom de class (après avoir été "sluggisée"

Un fichier php est donc généré dans le dossier Config/Migration du dossier app ou du dossier de votre plugin.

Celui-ci devrait ressembler à quelque chose comme cela : 

<?php
/**
 * On constate que le nom de la classe correspond à la desciption
 * que l'on a fournit
 */
class AddArticlesTable extends CakeMigration
{
    /**
     * Contient la structure de la base de données.
     * La clef "up" corresponds au modification à faire lors d'une migration
     * La clef "down" corresponds au modification à faire lors d'un retours en arrière
     */
    public $migration = [
        "up" => [
            "create_table" => [
                "articles" => [
                    "id" => [
                        "type" => "integer",
                        "null" => false,
                        "default" => null,
                        "key" => "primary",
                    ],
                    "title" => [
                        "type" => "string",
                        "null" => false,
                        "default" => null,
                        "collate" => "latin1_swedish_ci",
                        "charset" => "latin1",
                    ],
                    "content" => [
                        "type" => "string",
                        "null" => false,
                        "default" => null,
                        "collate" => "latin1_swedish_ci",
                        "charset" => "latin1",
                    ],
                    "indexes" => [
                        "PRIMARY" => ["column" => "id", "unique" => 1],
                    ],
                    "tableParameters" => [
                        "charset" => "latin1",
                        "collate" => "latin1_swedish_ci",
                        "engine" => "InnoDB",
                    ],
                ],
            ],
        ],
        "down" => [
            "drop_table" => ["articles"],
        ],
    ];

    /**
     * Les méthodes before et after on en parlera juste après.
     */
    public function before($direction)
    {
        return true;
    }
    public function after($direction)
    {
        return true;
    }
}

Vous remarquerez que le nom du fichier de la migration commence par un timestamp.

Appliquer une "Migration

Rien de plus simple. Il faut lancer la commande suivante : 

cake Migrations.Migration run all

# Ou, si vous souhaitez appliquer une migration d'un plugin
cake Migrations.Migration run all -p pluginName

Cette commande va exécuter toutes les migrations qui n'ont pas encore été effectuées. Le plugin "Migrations" utilise une table nommé schema_migrations pour connaître les migrations qui ont été exécutées.

Vous pouvez ensuite vous amuser en remplaçant le paramètre "all" par "reset", "down" et "up".

Conclusion

Pour cet exemple nous avons vu une application classique du plugin Migrations. Il nous a permit de mettre à jour une structure de table assez classique.

Le plugin Migrations permet aussi de gérer des migrations beaucoup plus complexes. Par exemple il permet d'appliquer des modifications sur les valeurs contenues sur la table que vous souhaitez modifier en passant par les méthodes before ou after .

Articles récents

Catégories

Tags