Migrations¶

Syntaxe¶

La syntaxe de la commande bake est de la forme suivante:

bin/cake bake migration CreateProducts name:string description:text created modified

Quand vous utilisez bake pour créer des tables, ajouter des colonnes ou effectuer diverses opérations sur votre base de données, vous devez en général fournir deux choses:

• le nom de la migration que vous allez générer (CreateProducts dans notre exemple)

• les colonnes de la table qui seront ajoutées ou retirées dans la migration (name:string description:text created modified dans notre exemple)

Étant données les conventions, tous les changements de schéma ne peuvent pas être effectuées avec les commandes shell.

De plus, vous pouvez créer un fichier de migration vide si vous voulez un contrôle total sur ce qui doit être executé, en ne spécifiant pas de définition de colonnes:

bin/cake migrations create MyCustomMigration

fieldName:fieldType?[length]:indexType:indexName

Créer une Table¶

Vous pouvez utiliser bake pour créer une table:

bin/cake bake migration CreateProducts name:string description:text created modified

La ligne de commande ci-dessus va générer un fichier de migration qui ressemble à:

<?php
use Migrations\AbstractMigration;

class CreateProducts extends AbstractMigration
{
    /**
     * Change Method.
     *
     * More information on this method is available here:
     * https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     * @return void
     */
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string', [
            'default' => null,
            'limit' => 255,
            'null' => false,
        ]);
        $table->addColumn('description', 'text', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('created', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('modified', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->create();
    }
}

Ajouter des Colonnes à une Table Existante¶

Si le nom de la migration dans la ligne de commande est de la forme « AddXXXToYYY » et est suivie d’une liste de noms de colonnes et de types alors un fichier de migration contenant le code pour la création des colonnes sera généré:

bin/cake bake migration AddPriceToProducts price:decimal

L’exécution de la ligne de commande ci-dessus va générer:

<?php
use Migrations\AbstractMigration;

class AddPriceToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('price', 'decimal')
              ->update();
    }
}

Ajouter un Index de Colonne à une Table¶

Il est également possible d’ajouter des indexes de colonnes:

bin/cake bake migration AddNameIndexToProducts name:string:index

va générer:

<?php
use Migrations\AbstractMigration;

class AddNameIndexToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string')
              ->addIndex(['name'])
              ->update();
    }
}

Spécifier la Longueur d’un Champ¶

Si vous voulez spécifier une longueur de champ, vous pouvez le faire entre crochets dans le type du champ, par exemple:

bin/cake bake migration AddFullDescriptionToProducts full_description:string[60]

L’exécution de la ligne de commande ci-dessus va générer:

<?php
use Migrations\AbstractMigration;

class AddFullDescriptionToProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('full_description', 'string', [
            'default' => null,
            'limit' => 60,
            'null' => false,
        ])
        ->update();
    }
}

Si aucune longueur n’est spécifiée, les longueurs pour certain types de colonnes sont par défaut:

• string: 255

• integer: 11

• biginteger: 20

Modifier une colonne d’une table¶

De la même manière, vous pouvez générer une migration pour modifier une colonne à l’aide de la commande ligne de commande, si le nom de la migration est de la forme « AlterXXXOnYYY »:

bin/cake bake migration AlterPriceOnProducts name:float

créé le fichier:

<?php
use Migrations\AbstractMigration;

class AlterPriceFromProducts extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->changeColumn('name', 'float');
        $table->update();
    }
}

Retirer une Colonne d’une Table¶

De la même façon, vous pouvez générer une migration pour retirer une colonne en utilisant la ligne de commande, si le nom de la migration est de la forme « RemoveXXXFromYYY »:

bin/cake bake migration RemovePriceFromProducts price

créé le fichier:

<?php
use Migrations\AbstractMigration;

class RemovePriceFromProducts extends AbstractMigration
{
    public function up()
    {
        $table = $this->table('products');
        $table->removeColumn('price')
              ->save();
    }
}

migrate : Appliquer les Migrations¶

Une fois que vous avez généré ou écrit votre fichier de migration, vous devez exécuter la commande suivante pour appliquer les modifications à votre base de données:

# Exécuter toutes les migrations
bin/cake migrations migrate

# Pour migrer vers une version spécifique, utilisez
# le paramètre ``--target`` ou -t (version courte)
# Cela correspond à l'horodatage qui est ajouté au début
# du nom de fichier des migrations.
bin/cake migrations migrate -t 20150103081132

# Par défaut, les fichiers de migration se trouvent dans
# le répertoire **config/Migrations**. Vous pouvez spécifier le répertoire
# en utilisant l'option ``--source`` ou ``-s`` (version courte).
# L'exemple suivant va exécuter les migrations
# du répertoire **config/Alternate**
bin/cake migrations migrate -s Alternate

# Vous pouvez exécuter les migrations avec une connection différente
# de celle par défaut ``default`` en utilisant l'option ``--connection``
# ou ``-c`` (version courte)
bin/cake migrations migrate -c my_custom_connection

# Les migrations peuvent aussi être exécutées pour les plugins. Utilisez
# simplement l'option ``--plugin`` ou ``-p`` (version courte)
bin/cake migrations migrate -p MyAwesomePlugin

rollback : Annuler les Migrations¶

La commande de restauration est utilisée pour annuler les précédentes migrations réalisées par ce plugin. C’est l’inverse de la commande migrate.:

# Vous pouvez annuler la migration précédente en utilisant
# la commande ``rollback``::
bin/cake migrations rollback

# Vous pouvez également passer un numéro de version de migration
# pour revenir à une version spécifique::
bin/cake migrations rollback -t 20150103081132

Vous pouvez aussi utilisez les options --source, --connection et --plugin comme pour la commande migrate.

status : Statuts de Migrations¶

La commande status affiche une liste de toutes les migrations, ainsi que leur état actuel. Vous pouvez utiliser cette commande pour déterminer les migrations qui ont été exécutées:

bin/cake migrations status

Vous pouvez aussi afficher les résultats avec le format JSON en utilisant l’option --format (ou -f en raccourci):

bin/cake migrations status --format json

Vous pouvez aussi utiliser les options --source, --connection et --plugin comme pour la commande migrate.

mark_migrated : Marquer une Migration en Migrée¶

Il peut parfois être utile de marquer une série de migrations comme « migrées » sans avoir à les exécuter. Pour ce faire, vous pouvez utiliser la commande mark_migrated. Cette commande fonctionne de la même manière que les autres commandes.

Vous pouvez marquer toutes les migrations comme migrées en utilisant cette commande:

bin/cake migrations mark_migrated

Vous pouvez également marquer toutes les migrations jusqu’à une version spécifique en utilisant l’option --target:

bin/cake migrations mark_migrated --target=20151016204000

Si vous ne souhaitez pas que la migration « cible » soit marquée, vous pouvez utiliser le _flag_ --exclude:

bin/cake migrations mark_migrated --target=20151016204000 --exclude

Enfin, si vous souhaitez marquer seulement une migration, vous pouvez utiliser le _flag_ --only:

bin/cake migrations mark_migrated --target=20151016204000 --only

Vous pouvez aussi utilisez les options --source, --connection et --plugin comme pour la commande migrate.

La commande attend le numéro de version de la migration comme argument:

bin/cake migrations mark_migrated 20150420082532

Si vous souhaitez marquer toutes les migrations comme « migrées », vous pouvez utiliser la valeur spéciale all. Si vous l’utilisez, toutes les migrations trouvées seront marquées comme « migrées »:

bin/cake migrations mark_migrated all

seed : Remplir votre Base de Données (Seed)¶

Depuis la version 1.5.5, vous pouvez utiliser le shell migrations pour remplir votre base de données. Cela vient de la fonctionnalité de seed de la librairie Phinx. Par défaut, les fichiers de seed vont être recherchés dans le répertoire config/Seeds de votre application. Assurez-vous de suivre les instructions de Phinx pour construire les fichiers de seed.

En ce qui concerne migrations, une interface bake est fournie pour les fichiers de seed:

# Ceci va créer un fichier ArticlesSeed.php dans le répertoire config/Seeds
# de votre application
# Par défaut, la table que le seed va essayer de modifier est la version
#  "tableized" du nom de fichier du seed
bin/cake bake seed Articles

# Vous spécifiez le nom de la table que les fichiers de seed vont modifier
# en utilisant l'option ``--table``
bin/cake bake seed Articles --table my_articles_table

# Vous pouvez spécifier un plugin dans lequel faire la création
bin/cake bake seed Articles --plugin PluginName

# Vous pouvez spécifier une connection alternative quand vous générez un
# seeder.
bin/cake bake seed Articles --connection connection

A partir de 1.6.4, la commande bake seed vous permet de créer des fichiers de seed avec des lignes exportées de votre base de données en utilisant l’option --data:

bin/cake bake seed --data Articles

Par défaut, cela exportera toutes les lignes trouvées dans la table. Vous pouvez limiter le nombre de lignes exportées avec l’option --limit:

# N'exportera que les 10 premières lignes trouvées
bin/cake bake seed --data --limit 10 Articles

Si vous ne souhaitez inclure qu’une sélection des champs de la table dans votre fichier de seed, vous pouvez utiliser l’option --fields. Elle prend la liste des champs séparés par une virgule comme argument:

# N'exportera que les champs `id`, `title` et `excerpt`
bin/cake bake seed --data --fields id,title,excerpt Articles

Pour faire un seed de votre base de données, vous pouvez utiliser la sous-commande seed:

# Sans paramètres, la sous-commande seed va exécuter tous les seeders
# disponibles du répertoire cible, dans l'ordre alphabétique.
bin/cake migrations seed

# Vous pouvez spécifier seulement un seeder à exécuter en utilisant
# l'option `--seed`
bin/cake migrations seed --seed ArticlesSeed

# Vous pouvez exécuter les seeders d'un autre répertoire
bin/cake migrations seed --source AlternativeSeeds

# Vous pouvez exécuter les seeders d'un plugin
bin/cake migrations seed --plugin PluginName

# Vous pouvez exécuter les seeders d'une connection spécifique
bin/cake migrations seed --connection connection

Notez que, à l’opposé des migrations, les seeders ne sont pas suivies, ce qui signifie que le même seeder peut être appliqué plusieurs fois.

use Migrations\AbstractSeed;

class DatabaseSeed extends AbstractSeed
{
    public function run(): void
    {
        $this->call('AnotherSeed');
        $this->call('YetAnotherSeed');

        // Vous pouvez utiliser la syntaxe "plugin" pour appeler un seeder
        // d'un autre plugin
        $this->call('PluginName.FromPluginSeed');
    }
}

dump : Générer un fichier dump pour la fonctionnalité de diff¶

La commande Dump crée un fichier qui sera utilisé avec le template bake migration_diff:

bin/cake migrations dump

Chaque fichier dump généré est spécifique à la _Connection_ par laquelle il a été générée (le nom du fichier est suffixé par ce nom). Cela permet à la commande bake migration_diff de calculer le diff correctement dans le cas où votre application gérerait plusieurs bases de données (qui pourraient être basées sur plusieurs SGDB.

Les fichiers de dump sont créés dans le même dossier que vos fichiers de migrations.

Vous pouvez aussi utiliser les options --source, --connection et --plugin comme pour la commande migrate.

Créer des Clés Primaires Personnalisées¶

Pour personnaliser la création automatique de la clé primaire id lors de l’ajout de nouvelles tables, vous pouvez utiliser le deuxième argument de la méthode table():

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{
    public function change()
    {
        $table = $this->table('products', ['id' => false, 'primary_key' => ['id']]);
        $table
              ->addColumn('id', 'uuid')
              ->addColumn('name', 'string')
              ->addColumn('description', 'text')
              ->create();
    }
}

Le code ci-dessus va créer une colonne CHAR(36) id également utilisée comme clé primaire.

bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

Depuis Migrations 1.3, une nouvelle manière de gérer les clés primaires a été introduite. Pour l’utiliser, votre classe de migration devra étendre la nouvelle classe Migrations\AbstractMigration. Vous pouvez définir la propriété autoId à false dans la classe de Migration, ce qui désactivera la création automatique de la colonne id. Vous aurez cependant besoin de manuellement créer la colonne qui servira de clé primaire et devrez l’ajouter à la déclaration de la table:

<?php
use Migrations\AbstractMigration;

class CreateProductsTable extends AbstractMigration
{

    public bool $autoId = false;

    public function up()
    {
        $table = $this->table('products');
        $table
            ->addColumn('id', 'integer', [
                'autoIncrement' => true,
                'limit' => 11
            ])
            ->addPrimaryKey('id')
            ->addColumn('name', 'string')
            ->addColumn('description', 'text')
            ->create();
    }
}

Comparée à la méthode précédente de gestion des clés primaires, cette méthode vous donne un plus grand contrôle sur la définition de la colonne de la clé primaire : signée ou non, limite, commentaire, etc.

Toutes les migrations et les snapshots créés avec bake utiliseront cette nouvelle méthode si nécessaire.

Collations¶

Si vous avez besoin de créer une table avec une collation différente de celle par défaut de la base de données, vous pouvez la définir comme option de la méthode table():

<?php
use Migrations\AbstractMigration;

class CreateCategoriesTable extends AbstractMigration
{
    public function change()
    {
        $table = $this
            ->table('categories', [
                'collation' => 'latin1_german1_ci'
            ])
            ->addColumn('title', 'string', [
                'default' => null,
                'limit' => 255,
                'null' => false,
            ])
            ->create();
    }
}

Notez cependant que ceci ne peut être fait qu’en cas de création de table : il n’y a actuellement aucun moyen d’ajouter une colonne avec une collation différente de celle de la table ou de la base de données. Seuls MySQL et SqlServer supportent cette option de configuration pour le moment.

Mettre à jour les Noms de Colonne et Utiliser les Objets Table¶

Si vous utilisez un objet Table de l’ORM de CakePHP pour manipuler des valeurs de votre base de données, comme renommer ou retirer une colonne, assurez-vous de créer une nouvelle instance de votre objet Table après l’appel à update(). Le registre de l’objet Table est nettoyé après un appel à update() afin de rafraîchir le schéma qui est reflèté et stocké dans l’objet Table lors de l’instanciation.

Migrations et déploiement¶

Si vous utilisez le plugin dans vos processus de déploiement, assurez-vous de vider le cache de l’ORM pour qu’il renouvelle les _metadata_ des colonnes de vos tables. Autrement, vous pourrez rencontrer des erreurs de colonnes inexistantes quand vous effectuerez des opérations sur vos nouvelles colonnes. Le Core de CakePHP inclut un Shell de Cache du Schéma que vous pouvez utilisez pour vider le cache:

// Avant 3.6, utilisez orm_cache
bin/cake schema_cache clear

Veuillez vous référer à la section du cookbook à propos du Shell du Cache du Schéma si vous voulez plus de détails à propos de ce shell.

Renommer une table¶

Le plugin vous donne la possibilité de renommer une table en utilisant la méthode rename(). Dans votre fichier de migration, vous pouvez utiliser la syntaxe suivante:

public function up()
{
    $this->table('old_table_name')
        ->rename('new_table_name');
}

Ne pas générer le fichier schema.lock¶

Pour que la fonctionnalité de « diff » fonctionne, un fichier .lock est généré à chaque que vous faites un migrate, un rollback ou que vous générez un snapshot via bake pour permettre de suivre l’état de votre base de données à n’importe quel moment. Vous pouvez empêcher que ce fichier ne soit généré, comme par exemple lors d’un déploiement sur votre environnement de production, en utilisant l’option --no-lock sur les commandes mentionnées ci-dessus:

bin/cake migrations migrate --no-lock

bin/cake migrations rollback --no-lock

bin/cake bake migration_snapshot MyMigration --no-lock