Map Files
Migrations generates two types of files.
The first is the map.php file, which keeps track of the migrations available, and the order in which they should be processed.
The second is the various migration instances themselves. Depending on the name you choose to give a migration, this filename will change.
map.php
<?php
$map = array(
1 => array(
'initial_schema' => 'M4b040dc7945c4db1b83f26347ff3ec9a'),
);
?>
The map.php file lists all the existing migrations for an application / plugin and is a map between their "public" file name and their "internal" class name.
Migrations are ordered by their creation date, so running cake migration generate will create a migration file placed at the end of the list.
Reordering migrations with the map file
Since the migration map file contains the order migrations are to be run in, reordering migrations in the map file will change the order in which they are executed. Take the following:
<?php
$map = array(
1 => array(
'initial_schema' => 'M4b040dc7945c4db1b83f26347ff3ec9a'),
2 => array(
'added_comment_count' => 'M4b040dc7945c4db1b83f26347fbb1a'),
3 => array(
'added_uploads_table' => 'M5b060dd7846c4cc1a53f26148fa11b'),
);
?>
Now if we wanted to reverse the order the 2nd and 3rd migration are to be run in, we can just re-order the items in the array.
<?php
$map = array(
1 => array(
'initial_schema' => 'M4b040dc7945c4db1b83f26347ff3ec9a'),
2 => array(
'added_uploads_table' => 'M5b060dd7846c4cc1a53f26148fa11b'),
3 => array(
'added_comment_count' => 'M4b040dc7945c4db1b83f26347fbb1a'),
);
?>
The order the migrations will be run in always reflects the order of elements in the $map.
Migration Files
<?php
class M4b040dc7945c4db1b83f26347ff3ec9a extends CakeMigration {
/**
* Migration description
*
* @var string
* @access public
*/
var $description = '';
/**
* Actions to be performed
*
* @var array $migration
* @access public
*/
var $migration = array(
'up' => array(
'create_table' => array(
'ingredients' => array(
'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
'name' => array('type' => 'string', 'null' => false, 'default' => NULL, 'length' => 100),
'indexes' => array(
'PRIMARY' => array('column' => 'id', 'unique' => 1),
),
'tableParameters' => array('charset' => 'latin1', 'collate' => 'latin1_swedish_ci', 'engine' => 'MyISAM'),
),
'ingredients_recipes' => array(
'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
'ingredient_id' => array('type' => 'integer', 'null' => false, 'default' => NULL),
'recipe_id' => array('type' => 'integer', 'null' => false, 'default' => NULL),
'indexes' => array(
'PRIMARY' => array('column' => 'id', 'unique' => 1),
),
'tableParameters' => array('charset' => 'latin1', 'collate' => 'latin1_swedish_ci', 'engine' => 'MyISAM'),
),
'recipes' => array(
'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
'user_id' => array('type' => 'integer', 'null' => false, 'default' => NULL),
'name' => array('type' => 'string', 'null' => false, 'default' => NULL, 'length' => 100),
'content' => array('type' => 'text', 'null' => false, 'default' => NULL),
'created' => array('type' => 'datetime', 'null' => false, 'default' => NULL),
'modified' => array('type' => 'datetime', 'null' => false, 'default' => NULL),
'indexes' => array(
'PRIMARY' => array('column' => 'id', 'unique' => 1),
),
'tableParameters' => array('charset' => 'latin1', 'collate' => 'latin1_swedish_ci', 'engine' => 'MyISAM'),
),
'users' => array(
'id' => array('type' => 'integer', 'null' => false, 'default' => NULL, 'key' => 'primary'),
'name' => array('type' => 'string', 'null' => false, 'default' => NULL, 'length' => 100),
'password' => array('type' => 'string', 'null' => false, 'default' => NULL),
'created' => array('type' => 'datetime', 'null' => false, 'default' => NULL),
'modified' => array('type' => 'datetime', 'null' => false, 'default' => NULL),
'indexes' => array(
'PRIMARY' => array('column' => 'id', 'unique' => 1),
),
'tableParameters' => array('charset' => 'latin1', 'collate' => 'latin1_swedish_ci', 'engine' => 'MyISAM'),
),
),
),
'down' => array(
'drop_table' => array(
'ingredients', 'ingredients_recipes', 'recipes', 'users'
),
),
);
/**
* Before migration callback
*
* @param string $direction, up or down direction of migration process
* @return boolean Should process continue
* @access public
*/
function before($direction) {
return true;
}
/**
* After migration callback
*
* @param string $direction, up or down direction of migration process
* @return boolean Should process continue
* @access public
*/
function after($direction) {
return true;
}
}
?>
This migration file contains all the information describing a migration.
$migration variable
The $migration variable contains two arrays describing actions to perform.
These actions are split into the directions the migration can operate: up or down.
Each set of actions describes schema changes that will be executed either when upgrading to this version or when downgrading from this version.
$description variable
The $description variable contains a readable description of the migration operations.
Callbacks
There are two callbacks that can be implemented: before($direction) and after($direction). These are, as you would expect, called before and after each migration.
The passed parameter $direction indicates whether the migration was up or down. You can use the value this variable to perform different actions on each callback, based on the direction the migration is going.
Callbacks are an ideal place to populate tables or fields with initial data, or to perform data transformations as fields and tables are adjusted through the lifetime of a migration set. Callbacks must return true in order for the migration to run. If either callback returns a non true value the migration will be considered as failed. Returning false from the before() callback is useful when you want to abort the migration based on some conditions, like the ability of the migration to maintain consistent data.
