File Source for migrator.php

<?php
/**
* This file contains the Migrator class.
*
* @package Migrator
* @author Gabriel Birke <birke@d-scribe.de>
* @copyright Copyright (C) 2007 by Gabriel Birke
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @version 0.5
*/
/**
*/
require_once 'MDB2.php';
require_once 'File/Util.php';
/**
* The Migrator class executes migration files - PHP files with
* {@link http://pear.php.net/package/MDB2 MDB2} instructions for database schema changes.
*
* With migrations you have a versioning scheme for database schema changes
* and you can always go back and forward to a known database schema - on all of your
* database servers (development, production and test). The currect schema version number is
* stored in a special table in your database.
*
* @author Gabriel Birke <birke@d-scribe.de>
*/
class Migrator
{
const VERSION = "0.7";
// Error codes
const ERROR_MIGRATION_DIR_MISSING = 1;
const ERROR_DB_CONNECT_FAILED = 2;
const ERROR_DB_QUERY_FAILED = 3;
const ERROR_INVALID_FILE_NAME = 4;
const ERROR_CLASS_NOT_FOUND = 5;
const ERROR_NO_MIGRATION_FILES = 6;
/**
* Table name where the schema versions are stored
* @var string
*/
public $schema_version_table = "schema_version";
/**
* Directory where th migration files are stored
* @var string
*/
protected $migrations_dir;
/**
* Data Source Name
*
* Example for a valid data source: mysql://my_user:my_pass@localhost/mydb
*
* @link http://pear.php.net/manual/en/package.database.mdb2.intro-dsn.php
* @var string
*/
protected $dsn;
/**
* Filenames, sorted by number prefix
* @var array
*/
protected $migration_files;
/**
* Highest number prefix in {@link $migration_files}
* @var int
*/
protected $migration_max_version;
/**
* Version to up/downgrade to
* @var int
*/
protected $target_version;
/**
* @var MDB2_Driver
*/
protected $db;
/**
* PEAR_Log or similar object
* @var Log
*/
protected $logger;
/**
* Initialize the internal variables.
*
* If you subclass Migrator, you must call this constructor!
*
* @param string $dsn Data Source Name
* @param int $target Version to up- or downgrade to (-1 for most recent version)
* @param string $migrations_dir Directory path where the the migration files are
* @param Log $logger PEAR_Log or similar object (must implement debug, error, notice and info methods)
*/
function __construct($dsn, $target_version, $migrations_dir, $logger)
{
$this->migrations_dir = $migrations_dir;
// Check migrations-dir
if(!file_exists($this->migrations_dir))
{
throw new Exception( "Migrations directory '{$this->migrations_dir}' does not exist.",
Migrator::ERROR_MIGRATION_DIR_MISSING);
}
// Collect migration file names
$this->collectMigrationFiles();
if(empty($this->migration_files))
{
throw new Exception( "No migration files.", Migrator::ERROR_NO_MIGRATION_FILES);
}
$this->dsn = $dsn;
$this->logger = $logger;
$this->target_version = ($target_version == -1)?$this->migration_max_version:$target_version;
}
/**
* The main function that does the migration.
*
* Connects to the database, reads the current schema version, decides to up-
* or downgrade, loads the matching migrations, executes them and updates
* the schema version.
*/
function run()
{
$this->connect();
$this->initializeCurrentSchemaVersion();
if($this->current_version == $this->target_version)
{
$this->log("Database ist at selected version, nothing to be done.", "info");
return;
}
$direction = $this->getMigrationDirection();
$this->filterAndSortMigrationFiles($direction);
// Do the migrations
$this->migrate($direction);
}
/**
* Collects migration file names from {@link $migrations_dir} and stores them
* in the sorted array {@link $migration_files}.
*
* {@link $migration_max_version} is set to the biggest migration file prefix number.
*/
protected function collectMigrationFiles()
{
$this->migration_files = array();
$it = new DirectoryIterator($this->migrations_dir);
foreach($it as $file)
{
if($file->isFile() && preg_match('/^\d+_?[a-zA-Z0-9_]/', $it->getFileName()))
$this->migration_files[] = $it->getFileName();
}
sort($this->migration_files, SORT_NUMERIC);
$this->migration_max_version = $this->migrationFileNumber(end($this->migration_files));
reset($this->migration_files);
}
/**
* Initializes {@link $db} with an instance of a MDB2 database driver.
*
* The MDB2 "Manager" module is also loaded for the driver.
*/
protected function connect()
{
$options = array();
$this->db = MDB2::connect($this->dsn, $options);
if (PEAR::isError($this->db)) {
throw new Exception("Failed to conect to '{$this->dsn}': ".$this->db->getMessage()."\n".$this->db->getUserinfo(), <a href="../Migrator/Migrator.html">Migrator</a>::ERROR_DB_CONNECT_FAILED);
}
$this->db->loadModule('Manager', null, true);
}
/**
* Initializes {@link $current_version} with version number from
* {@link $schema_version_table}.
*
* If the table doesn't exist, initialize with 0 and create the table.
*/
protected function initializeCurrentSchemaVersion()
{
$tables = $this->db->listTables();
if(!in_array($this->schema_version_table, $tables))
{
$fields = array(
'version' => array(
'type' => 'integer',
'notnull' => true,
'unsigned' => true
)
);
$this->checkDBResult($this->db->createTable($this->schema_version_table, $fields));
$this->checkDBResult($this->db->exec("INSERT INTO {$this->schema_version_table} (version) VALUES (0)"));
}
else
$this->current_version = 0;
$res = $this->db->query("SELECT version FROM {$this->schema_version_table} LIMIT 1");
$this->checkDBResult($res);
$this->current_version = $res->fetchOne();
}
protected function getMigrationDirection()
{
if($this->target_version > $this->current_version)
{
$direction = "up";
}
else
{
$direction = "down";
}
$this->log("{$direction}grading from version {$this->current_version} to {$this->target_version}.", "info");
return $direction;
}
/**
* Leave only files in $this->migration_files that are needen for up/downgrade.
*
* @param string $direction "up" or "down"
*/
protected function filterAndSortMigrationFiles($direction)
{
$func_name = "_filter_{$direction}grade";
$this->log("Calling function '$func_name'.");
$this->migration_files = array_filter($this->migration_files, array($this, $func_name));
if($direction == "up")
sort($this->migration_files, SORT_NUMERIC);
else
rsort($this->migration_files, SORT_NUMERIC);
$this->log("The following migration files are left after filtering: ".implode(', ', $this->migration_files));
}
/**
* Load each class in {@link $migration_files} and call its "up" or "down" method
*
* @param string $direction "up" or "down"
*/
protected function migrate($direction)
{
$classes = array();
// Load the class files and check if the class we expect exists
foreach($this->migration_files as $file)
{
if(!preg_match('/(\d+)_?([a-zA-Z0-9_]+)/', $file, $matches))
{
// Should not happen if migrationFiles were set with collectMigrationFiles
throw new Exception("Invalid file name: $file", Migrator::ERROR_INVALID_FILE_NAME);
}
$class = $matches[2];
$migration_id = $matches[1];
$fn = File_Util::buildpath(array($this->migrations_dir, $file));
$this->log("Loading File '$fn'.", 'debug');
require_once $fn;
if(!class_exists($class))
{
throw new Exception("Class '$class' not found.", Migrator::ERROR_CLASS_NOT_FOUND);
}
// TODO check if the class implements IMigration
$classes[$migration_id] = $class;
}
// If we downgrade, we must subtract one from the migration id
$id_factor = $direction=="down"?-1:0;
// Call each classes up/down method
// This second loop ensured that no database mordifications are made
// when there is a syntax error in one of the loaded classes.
foreach($classes as $migration_id => $class)
{
$this->log("Doing Migration '$class'.", 'info');
call_user_func(array($class, 'init'), $this->logger);
$return = call_user_func(array($class, $direction), $this->db);
if(PEAR::isError($return))
{
throw new Exception($return->getMessage()."\n".$return->getUserinfo(), Migrator::ERROR_DB_QUERY_FAILED);
}
// Write new migration version (create version table if it doesn't exist)
$this->writeNewMigrationVersion($migration_id + $id_factor);
}
return true;
}
/**
* Write the new version number into {$schema_version_table}.
*/
protected function writeNewMigrationVersion($newVersion)
{
$newVersion = max(0, $newVersion);
$this->log("Changing schema version to $newVersion", 'debug');
$this->checkDBResult($this->db->exec("UPDATE {$this->schema_version_table} SET version = {$newVersion}"));
}
/**
* Return the migration file number at the start of a filename.
*
* @param string $filename
* @return int
*/
protected function migrationFileNumber($filename)
{
preg_match('/^(\d+)/', $filename, $matches);
return intval($matches[1]);
}
/**
* Callback function for {@link array_filter()} that returns true for migration files
* between {@link $current_version} and {@link $target_version}.
*
* @param string $filename
* @return boolean
*/
protected function _filter_upgrade($filename)
{
$number = $this->migrationFileNumber($filename);
return $number <= $this->target_version && $number > $this->current_version;
}
/**
* Callback function for {@link array_filter()} that returns true for migration files
* between {@link $target_version} and {@link $current_version}.
*
* @param string $filename
* @return boolean
*/
protected function _filter_downgrade($filename)
{
$number = $this->migrationFileNumber($filename);
return $number > $this->target_version && $number <= $this->current_version;
}
/**
* If the result given is an error, throw an exception.
*
* @param MDB2_Result $result
*/
protected function checkDBResult($result)
{
if (PEAR::isError($result)) {
throw new Exception($result->getMessage(), Migrator::ERROR_DB_QUERY_FAILED);
}
}
function log($message, $level="debug")
{
if($this->logger)
$this->logger->$level($message);
}

Documentation generated on Sat, 09 Jun 2007 11:50:10 +0200 by phpDocumentor 1.3.2

Source for file migrator.php