Toutes les migrations étendant la classe Phigrate_Migration_Base doivent être préfixée par $this (e.g. $this->addColumn()).

Les méthodes disponibles sont (brève liste ci-dessous, avec l'utilisation détaillée plus bas):

• createDatabase
• dropDatabase

• createTable
• dropTable
• renameTable

• addColumn
• removeColumn
• renameColumn
• changeColumn

• addIndex
• removeIndex

• execute
• selectOne
• selectAll

Il y a deux opérations de niveau Database, createDatabase et dropDatabase. Les migrations qui manipulent les bases de données de haut niveau sont rarement utilisées.

Cette commande est un peu inutile car normalement vous devez faire tourner votre migration sur une base de données existante (créer et initialiser avec vos méthodes traditionnelles de votre SGBDR). Toutefois, si vous vouliez créer une autre base de données à partir d'une migration, cette méthode est disponible:

Méthode a appeler: createDatabase

Arguments

• name : Nom de la nouvelle base de données

Exemple:

<?php
    $this->createDatabase("my_project");
?>

Pour supprimer complètement une base de données et toutes ces tables (et données!).

Méthode a appeler: dropDatabase

Arguments

• name : Nom de la base existante

Exemple:

<?php
    $this->dropDatabase("my_project");
?>

Le framework de migration de base de données offre une riche facilité pour créer, supprimer et renommer les tables.

Cette méthode est probablement la plus complexe des méthodes, mais aussi la plus utilisée.

Méthode a appeler: createTable

Arguments

• name : Nom de la nouvelle table

• options : (Optionel) Un tableau associatif d'options pour créer une nouvelle table.

Les options (key/value) supportées sont:

• id: Boolean - si oui ou non le framework doit générer automatiquement une clé primaire. Pour MySQL la colonne sera appelée id et être de type entier avec auto-incrémentation.

• options: Une chaîne représentant les paramètres de finalisation qui sera passée verbatim à la queue de la commande CREATE TABLE. Souvent, cela est utilisé pour spécifier le moteur de stockage pour MySQL (e.g. 'options' => 'Engine=InnoDB').

Hypothèses En définitif, cette méthode délègue à l'adaptateur approprié du SGBDR et l'adaptateur MySQL rend certaines hypothèses importantes sur la structure de la table.

Un appel à $this->createTable(...) retourne en fait une TableDefinition objet. Cette méthode du framework est l'une des très rares qui retourné en réalité un résultat avec lequel vous devez interagir (en tant qu'utilisateurs finaux).

Ces étapes pour créer une nouvelle table sont:

• Créer la table avec le nom et les options fournies et stocker la valeur de retour pour une utilisation ultérieure:

<?php
    $users = $this->createTable("users");
?>

• Ajouter des colonnes à la définition de la table:

<?php
    $users->column("first_name", "string");
    $users->column("last_name", "string");
?>

• Appeler finish() pour créer effectivement la table avec la définition et de ses colonnes:

<?php
    $users->finish();
?>

Par défaut, le type de table sera celui par défaut de votre base de données. Pour spécifier un type de table différent (e.g. InnoDB), passez la clé options dans le tableau $options, par exemple:

Exemple A: Créer une nouvelle table InnoDB nommée users.

<?php
    $this->createTable('users', array('options' => 'Engine=InnoDB'));
?>

• Cette commande suppose aussi que vous voulez une colonne id. Cette colonne n'a pas besoin d'être spécifiée, ce sera généré automatiquement, sauf s'il est explicitement demandé via la clef id dans le tableau $options.

Exemple B: Créer une nouvelle table nommée users mais sans réaliser automatiquement la clef primaire.

<?php
    $this->createTable('users', array('id' => false));
?>

La colonne clef primaire devra être créée avec les attributs int(11) unsigned auto_increment.

Exemple C: Pour spécifier votre propre clé primaire appelée "GUID":

<?php
    $t = $this->createTable('users', array('id' => false, 'options' => 'Engine=InnoDB'));
    $t->column('guid', 'string', array('primary_key' => true, 'limit' => 64));
    $t->finish();
?>

Les tables peuvent être supprimées en utilisant la méthode dropTable. Comme on pouvait s'y attendre, supprimer une table supprime aussi toutes ses colonnes et ses index.

Méthode a appeler: dropTable

Arguments::

• tableName: Le nom de la table à supprimer.

Les tables peuvent être renommées en utilisant la méthode renameTable.

Méthode à appeler: renameTable

Arguments:

• tableName: Le nom actuel de la table.
• newName: Le nouveau nom de la table.

Pour une documentation complète sur l'ajout de colonnes, veuillez voir Ajouter des colonnes

Supprimer une colonne de base de données est très simple, but garder à l'esprit que tous les index associés avec cette colonne seront aussi supprimés.

Méthode à appeler: removeColumn

Arguments

• tableName: Le nom de la table où se trouve la colonne qui sera supprimée.

• columnName: La colonne a supprimer.

Exemple A: Supprimer la colonne age de la table users.

<?php
    $this->removeColumn("users", "age"); 
?>

Les colonnes de base de données peuvent être renommées (en supposant que le SGBDR/adaptateur le supporte).

Méthode à appeler: renameColumn

Arguments:

• tableName: Le nom de la table où se trouve la colonne à renommer.

• columnName: Le nom actuel de la colonne.

• newColumnName: Le nouveau nom de la colonne.

Exemple A: Dans la table users, renommez first_name par fname.

<?php
    $this->renameColumn("users", "first_name", "fname");
?>

Attention: Cette méthode ne gère pas l'export avec la tâche db:export. Utilisez plutôt la méthode suivante avec l'option 'new_name'.

Le type, par défaut ou NULL supporté pour les colonnes existantes peut être modifié. Si vous souhaitez simplement renommer une colonne, alors utilisez la méthode renameColumn. Cette méthode prend un type générique pour le type de la colonne et aussi un tableau d'options qui affecteront la définition de la colonne. Pour les types et les options disponibles, voir la documentation sur l'ajout de nouvelles colonnes, Ajouter des colonnes.

Méthode à appeler: changeColumn

Arguments:

• tableName: Le nom de la table où se trouve la colonne à modifier.

• columnName: Le nom de la colonne à changer.

• type: Le type générique de la colonne.

• options: (Optionel) Un tableau d'options associatif pour la définition de la colonne.

Exemple A: Dans la table users, changez la longueur de la colonne first_name à 128 caractères.

<?php
    $this->changeColumn("users", "first_name", "string", array('limit' => 128) );
?>

Les index peuvent être créés et supprimés en utilisant les méthodes du framework.

Méthode à appeler: addIndex

Arguments:

• table: Le nom de la table où ajouter l'index.

• column: La colone sur laquelle on crée l'index. Si cela est une chaîne, alors il est présumé être le nom de la colonne, et l'index sera un index de colonne unique. S'il c'est un tableau, alors il est présumé être une liste de noms de colonnes et de l'index sera alors un index multi-colonne, sur les colonnes spécifiées.

• options: (Optionel) Un tableau associatif d'options qui contrôle la

• génération de l'index. paires de clefs / valeurs:

  • unique: valeurs: true ou false. Que ce soit ou non créer un index unique pour cette colonne. Valeurs par défaut est false.

  • name : valeurs: définit par l'utilisateur. Le nom de l'index. Si il n'est pas spécifié, un nom par défaut sera généré à partir du nom de la table et de la colonne.

Problèmes connus / Coutournements: MySQL est actuellement limité à 64 caractères pour les noms d'identificateur. Lorsque _add_index_ est utilisé sans spécifier le nom de l'index, Phigrate va générer un nom approprié basé sur le nom de la table et de la/les colonne(s). Par exemple, si il y a une table users et un index est généré sur la colonne username alors le nom de l'index généré sera: idx_users_username. Si l'on tente d'ajouter un index multi-colonne, il est fort possible que le nom généré sera plus long que la limite de MySQL de 64 caractères. Dans de telles situations Phigrate déclenche une erreur suggérant d'utiliser un nom d'index personnalisé via le paramètre option name. Voir Exemple C.

Exemple A: Créer un index sur la colonne email de la table users.

<?php
    $this->addIndex("users", "email");
?>

Exemple B: Créer un index unique sur la colonne ssn de la table users.

<?php
    $this->addIndex("users", "ssn", array('unique' => true)));
?>

Exemple C: Créer un index sur la colonne blog_id de la table posts, mais en spécifiant un nom personnalisé pour l'index.

<?php
    $this->addIndex("posts", "blog_id", array('name' => 'index_on_blog_id'));
?>

Exemple D: Créer un index multi-colonnes sur les colonnes email et ssn de la table users.

<?php
    $this->addIndex("users", array('email', 'ssn') );
?>

Assez facile. Si l'index a été créé en utilisant la méthode addIndex, alors on a juste besoin de spécifier les mêmes arguments que l'autre méthode (mais en appelant removeIndex).

Méthode à appeler: removeIndex

Arguments:

• tableName: Le nom de la table où doit être supprimé l'index.

• columnName: Le nom de la colonne sur laquelle doit être supprimer l'index.

• options: (Optionel) Un tableau associatif d'options pour contrôler la suppression de l'index. Les paires clefs / valeurs :

  • name : valeur: définit par l'utilisateur. Le nom de l'index à supprimer.

Exemple A: Supprimer l'index (simple-colonne) de la table users sur la colonne email.

<?php
    $this->removeIndex("users", "email");
?>

Exemple B: Supprimer un index (multi-colonnes) de la table users sur les colonnes email et ssn.

<?php
    $this->removeIndex("users", array("email", "ssn") );
?>

Exemple C: Supprimer un index nommé (simple-colonne) de la table users sur la colonne email.

<?php
    $this->removeIndex("users", "email", array('name' => "index_on_email_column") );
?>

L'exécution des requêtes arbitraires est disponible via un ensemble de méthodes.

La méthode execute() est destinée pour les requêtes qui ne renvoient pas de données, e.g. INSERT, UPDATE or DELETE.

Exemple A: Mise à jour de toutes les lignes répondant à un critère.

<?php
    $this->execute("UPDATE foo SET name = 'bar' WHERE .... ");
?>

Pour les requêtes qui retournent des résultats, e.g. requêtes SELECT, utilisez selectOne ou selectAll en fonction de ce que vous attendez comme retour.

Ces deux méthodes retournent un tableau associatif avec chaque élément du tableau étant lui-même un autre tableau associatif des noms de colonnes et leurs valeurs.

selectOne() est destiné pour des requêtes où l'on attend un seul jeu de résultats, et selectAll() est destiné à tous les autres cas (où l'on pourrait ne pas nécessairement savoir combien de lignes on obtiendra).

NOTE: Puisque ces méthodes prennent des requêtes SQL en entrée, elles ne sont pas nécessairement portables dans tous les SGBDR.

Exemple A (selectOne): Recupérer la somme de la colonne

<?php
    $result = $this->selectOne("SELECT SUM(total_price) AS total_price FROM orders");
    if($result) {
     echo "Your revenue is: " . $result['total_price'];
    }
?>

Exemple B (selectAll): Recupérer toutes les lignes et itérer sur chacune en effectuant une opération:

<?php
    $result = $this->selectAll("SELECT email, first_name, last_name FROM users WHERE created_at >= SUBDATE( NOW(), INTERVAL 7 DAY)");

    if($result) {
      echo "New customers: (" . count($result) . ")\n";
      foreach($result as $row) {
        printf("(%s) %s %s\n", $row['email'], $row['first_name'], $row['last_name']);
      }
    }
?>