Les migrations vous permettent de gérer plus facilement les évolutions du schéma de votre base de données. Vous pouvez par exemple créer un fichier de migration pour ajouter un nouveau champ à l'une des tables, tester votre code en local, puis déployer le changement sur le serveur de production, tout en conservant la possibilité de revenir à une version antérieure de votre schéma.

Exemple d'une création de table :

class AddTodos extends SMigration
{
    public function up()
    {
        $t = new STable();
        $t->add_primary_key('id');
        $t->add_column('user_id', 'integer');
        $t->add_column('lib', 'text');
        $t->add_column('done', 'boolean');
        $t->add_column('done_on', 'datetime');
 
        $this->create_table('todos', $t);
    }
 
    public function down()
    {
        $this->drop_table('todos');
    }
}

Cette migration créera une table todos et la supprimera si vous décidez de revenir à la version antérieure. Vous pouvez également include du code PHP pour alimenter en données la table.

Exemple d'un ajout de champ :

class AddTimestamp extends SMigration
{
    public function up()
    {
        $this->add_column('todos', 'created_on', 'datetime');
    }
 
    public function down()
    {
        $this->remove_column('todos', 'created_on');
    }
}

Cette migration ajoutera un champ created_on à la table todos.

Notez que les migrations utilisent une table schema_info qui sera créée automatiquement dans votre base lors de la première exécution d'une migration.

Toutes les méthodes du driver de votre base de données sont disponibles, en particulier :

• create_table($name, $table_def, $options = array())
• rename_table($old_name, $new_name)
• drop_table($name)
• add_column($table_name, $column_name, $type, $options = array())
• remove_column($table_name, $column_name)
• change_column($table_name, $column_name, $type, $options = array())
• rename_column($table_name, $column_name, $new_name)
• add_index($table_name, $column_name, $options = array())
• remove_index($table_name, $options = array())

Lors de la génération d'une classe modèle par le script generate.php, un fichier de migration sera créé automatiquement. Vous pouvez également en générer un directement par la commande suivante :

php scripts/generate.php migration add_users_table

Cette commande génèrera une class AddUsersTable dans le fichier n_add_users_table.php, où n est le numéro de version suivant. Vous n'aurez plus qu'à éditer les méthodes up et down de votre classe de migration.

Pour exécuter la migration, utilisez la commande :

php scripts/migrate.php

Cela mettra à jour votre base en exécutant tous les fichiers de migration en attente. Pour revenir à une version antérieure de votre base, utilisez la commande :

php scripts/migrate.php --version=15
OU
php scripts/migrate.php -v 15

Une migration peut parfois modifier la base à un tel point qu'aucun retour en arrière n'est possible. Dans ce cas, la méthode down() de votre classe de migration doit lever une exception de classe SIrreversibleMigrationException.

Vous pouvez avoir besoin de créer une nouvelle colonne et d'y intégrer des valeurs juste après en utilisant la classe modèle correspondante. Pour cela, réinitialisez le mapping de la table à l'aide de SMapper::reset_meta_information() :

class AddVATPrice extends SMigration
{
    public function up()
    {
        $this->add_column('products', 'vat_price', 'float');
        SMapper::reset_meta_information('Product');
        foreach (Product::$objects->all() as $p)
            $p->update_attribute('vat_price', $p + (20.5 * $p));
    }
    ...
}