Merge pull request #1949 from compwright/develop

Added support for timestamp-based migrations

5 files changed, 209 insertions, 128 deletions

diff --git a/application/config/migration.php b/application/config/migration.php
index 7645ade7c..3ea3ef93c 100644
--- a/application/config/migration.php
+++ b/application/config/migration.php
@@ -39,6 +39,24 @@ $config['migration_enabled'] = FALSE;
 
 /*
 |--------------------------------------------------------------------------
+| Migration Type
+|--------------------------------------------------------------------------
+|
+| Migration file names may be based on a sequential identifier or on
+| a timestamp. Options are:
+|
+|   'sequential' = Default migration naming (001_add_blog.php)
+|   'timestamp'  = Timestamp migration naming (20121031104401_add_blog.php)
+|                  Use timestamp format YYYYMMDDHHIISS.
+|
+| If this configuration value is missing the Migration library defaults
+| to 'sequential' for backward compatibility.
+|
+*/
+$config['migration_type'] = 'timestamp';
+
+/*
+|--------------------------------------------------------------------------
 | Migrations table
 |--------------------------------------------------------------------------
 |
diff --git a/system/language/english/migration_lang.php b/system/language/english/migration_lang.php
index 714a1e304..689a72952 100644
--- a/system/language/english/migration_lang.php
+++ b/system/language/english/migration_lang.php
@@ -28,6 +28,7 @@ defined('BASEPATH') OR exit('No direct script access allowed');
 
 $lang['migration_none_found']			= 'No migrations were found.';
 $lang['migration_not_found']			= 'No migration could be found with the version number: %d.';
+$lang['migration_sequence_gap']         = 'There is a gap in the migration sequence near version number: %d.';
 $lang['migration_multiple_version']		= 'There are multiple migrations with the same version number: %d.';
 $lang['migration_class_doesnt_exist']	= 'The migration class "%s" could not be found.';
 $lang['migration_missing_up_method']	= 'The migration class "%s" is missing an "up" method.';
diff --git a/system/libraries/Migration.php b/system/libraries/Migration.php
index 06f2f562c..27d7df010 100644
--- a/system/libraries/Migration.php
+++ b/system/libraries/Migration.php
@@ -46,6 +46,13 @@ class CI_Migration {
 	 * @var bool
 	 */
 	protected $_migration_enabled = FALSE;
+	
+	/**
+	 * Migration numbering type
+	 *
+	 * @var bool
+	 */
+	protected $_migration_type = 'sequential';
 
 	/**
 	 * Path to migration classes
@@ -74,6 +81,13 @@ class CI_Migration {
 	 * @var bool
 	 */
 	protected $_migration_auto_latest = FALSE;
+	
+	/**
+	 * Migration basename regex
+	 *
+	 * @var bool
+	 */
+	protected $_migration_regex = NULL;
 
 	/**
 	 * Error message
@@ -126,12 +140,23 @@ class CI_Migration {
 		{
 			show_error('Migrations configuration file (migration.php) must have "migration_table" set.');
 		}
+		
+		// Migration basename regex
+		$this->_migration_regex = ($this->_migration_type === 'timestamp')
+		                        ? '/^\d{14}_(\w+)$/'
+		                        : '/^\d{3}_(\w+)$/';
+		
+		// Make sure a valid migration numbering type was set.
+		if ( ! in_array($this->_migration_type, array('sequential', 'timestamp')))
+		{
+			show_error('An invalid migration numbering type was specified: '.$this->_migration_type);
+		}
 
 		// If the migrations table is missing, make it
 		if ( ! $this->db->table_exists($this->_migration_table))
 		{
 			$this->dbforge->add_field(array(
-				'version' => array('type' => 'INT', 'constraint' => 3),
+				'version' => array('type' => 'BIGINT', 'constraint' => 20),
 			));
 
 			$this->dbforge->create_table($this->_migration_table, TRUE);
@@ -159,113 +184,81 @@ class CI_Migration {
 	 */
 	public function version($target_version)
 	{
-		$start = $current_version = $this->_get_version();
-		$stop = $target_version;
-
+		$current_version = (int) $this->_get_version();
+		$target_version = (int) $target_version;
+		
+		$migrations = $this->find_migrations();
+		
+		if ($target_version > 0 && ! isset($migrations[$target_version]))
+		{
+			$this->_error_string = sprintf($this->lang->line('migration_not_found'), $target_version);
+			return FALSE;
+		}
+		
 		if ($target_version > $current_version)
 		{
 			// Moving Up
-			++$start;
-			++$stop;
-			$step = 1;
+			$method = 'up';
 		}
 		else
 		{
-			// Moving Down
-			$step = -1;
+			// Moving Down, apply in reverse order
+			$method = 'down';
+			krsort($migrations);
 		}
 
-		$method = $step === 1 ? 'up' : 'down';
-		$migrations = array();
-
-		// We now prepare to actually DO the migrations
-		// But first let's make sure that everything is the way it should be
-		for ($i = $start; $i != $stop; $i += $step)
+		if (empty($migrations))
 		{
-			$f = glob(sprintf($this->_migration_path.'%03d_*.php', $i));
+			return TRUE;
+		}
+		
+		$previous = FALSE;
 
-			// Only one migration per step is permitted
-			if (count($f) > 1)
+		// Validate all available migrations, and run the ones within our target range
+		foreach ($migrations as $number => $file)
+		{
+			// Check for sequence gaps
+			if ($this->_migration_type === 'sequential' && $previous !== FALSE && abs($number - $previous) > 1)
 			{
-				$this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $i);
+				$this->_error_string = sprintf($this->lang->line('migration_sequence_gap'), $number);
 				return FALSE;
 			}
+		
+			include $file;
+			$class = 'Migration_'.ucfirst(strtolower($this->_get_migration_name(basename($file, '.php'))));
 
-			// Migration step not found
-			if (count($f) === 0)
+			// Validate the migration file structure
+			if ( ! class_exists($class))
 			{
-				// If trying to migrate up to a version greater than the last
-				// existing one, migrate to the last one.
-				if ($step === 1)
-				{
-					break;
-				}
-
-				// If trying to migrate down but we're missing a step,
-				// something must definitely be wrong.
-				$this->_error_string = sprintf($this->lang->line('migration_not_found'), $i);
+				$this->_error_string = sprintf($this->lang->line('migration_class_doesnt_exist'), $class);
 				return FALSE;
 			}
-
-			$file = basename($f[0]);
-			$name = basename($f[0], '.php');
-
-			// Filename validations
-			if (preg_match('/^\d{3}_(\w+)$/', $name, $match))
+			elseif ( ! is_callable(array($class, $method)))
 			{
-				$match[1] = strtolower($match[1]);
-
-				// Cannot repeat a migration at different steps
-				if (in_array($match[1], $migrations))
-				{
-					$this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $match[1]);
-					return FALSE;
-				}
-
-				include $f[0];
-				$class = 'Migration_'.ucfirst($match[1]);
-
-				if ( ! class_exists($class))
-				{
-					$this->_error_string = sprintf($this->lang->line('migration_class_doesnt_exist'), $class);
-					return FALSE;
-				}
-
-				if ( ! is_callable(array($class, $method)))
-				{
-					$this->_error_string = sprintf($this->lang->line('migration_missing_'.$method.'_method'), $class);
-					return FALSE;
-				}
-
-				$migrations[] = $match[1];
+				$this->_error_string = sprintf($this->lang->line('migration_missing_'.$method.'_method'), $class);
+				return FALSE;
 			}
-			else
+			
+			$previous = $number;
+
+			// Run migrations that are inside the target range
+			if (
+				($method === 'up'   && $number > $current_version && $number <= $target_version) OR
+				($method === 'down' && $number <= $current_version && $number > $target_version)
+			)
 			{
-				$this->_error_string = sprintf($this->lang->line('migration_invalid_filename'), $file);
-				return FALSE;
+				log_message('debug', 'Migrating '.$method.' from version '.$current_version.' to version '.$number);
+				call_user_func(array(new $class, $method));
+				$current_version = $number;
+				$this->_update_version($current_version);
 			}
 		}
-
-		log_message('debug', 'Current migration: '.$current_version);
-
-		$version = $i + ($step === 1 ? -1 : 0);
-
-		// If there is nothing to do so quit
-		if ($migrations === array())
+		
+		// This is necessary when moving down, since the the last migration applied
+		// will be the down() method for the next migration up from the target
+		if ($current_version <> $target_version)
 		{
-			return TRUE;
-		}
-
-		log_message('debug', 'Migrating from '.$method.' to version '.$version);
-
-		// Loop through the migrations
-		foreach ($migrations AS $migration)
-		{
-			// Run the migration class
-			$class = 'Migration_'.ucfirst(strtolower($migration));
-			call_user_func(array(new $class, $method));
-
-			$current_version += $step;
+			$current_version = $target_version;
 			$this->_update_version($current_version);
 		}
 
@@ -283,17 +276,19 @@ class CI_Migration {
 	 */
 	public function latest()
 	{
-		if ( ! $migrations = $this->find_migrations())
+		$migrations = $this->find_migrations();
+		
+		if (empty($migrations))
 		{
 			$this->_error_string = $this->lang->line('migration_none_found');
 			return FALSE;
 		}
 
 		$last_migration = basename(end($migrations));
-
+		
 		// Calculate the last migration step from existing migration
 		// filenames and procceed to the standard version migration
-		return $this->version((int) $last_migration);
+		return $this->version($this->_get_migration_number($last_migration));
 	}
 
 	// --------------------------------------------------------------------
@@ -327,22 +322,60 @@ class CI_Migration {
 	 *
 	 * @return	array	list of migration file paths sorted by version
 	 */
-	protected function find_migrations()
+	public function find_migrations()
 	{
+		$migrations = array();
+	
 		// Load all *_*.php files in the migrations path
-		$files = glob($this->_migration_path.'*_*.php');
-
-		for ($i = 0, $c = count($files); $i < $c; $i++)
+		foreach (glob($this->_migration_path.'*_*.php') as $file)
 		{
-			// Mark wrongly formatted files as false for later filtering
-			if ( ! preg_match('/^\d{3}_(\w+)$/', basename($files[$i], '.php')))
+			$name = basename($file, '.php');
+		
+			// Filter out non-migration files
+			if (preg_match($this->_migration_regex, $name))
 			{
-				$files[$i] = FALSE;
+				$number = $this->_get_migration_number($name);
+				
+				// There cannot be duplicate migration numbers
+				if (isset($migrations[$number]))
+				{
+					$this->_error_string = sprintf($this->lang->line('migration_multiple_version'), $number);
+					show_error($this->_error_string);
+				}
+				
+				$migrations[$number] = $file;
 			}
 		}
 
-		sort($files);
-		return $files;
+		ksort($migrations);
+		return $migrations;
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Extracts the migration number from a filename
+	 *
+	 * @return	int Numeric portion of a migration filename
+	 */
+	protected function _get_migration_number($migration)
+	{
+		$parts = explode('_', $migration);
+		return (int) $parts[0];
+	}
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Extracts the migration class name from a filename
+	 *
+	 * @return	string text portion of a migration filename
+	 */
+	protected function _get_migration_name($migration)
+	{
+		$parts = explode('_', $migration);
+		array_shift($parts);
+		return implode('_', $parts);
 	}
 
 	// --------------------------------------------------------------------
@@ -366,10 +399,10 @@ class CI_Migration {
 	 * @param	int	Migration reached
 	 * @return	void	Outputs a report of the migration
 	 */
-	protected function _update_version($migrations)
+	protected function _update_version($migration)
 	{
 		return $this->db->update($this->_migration_table, array(
-			'version' => $migrations
+			'version' => $migration
 		));
 	}
 
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index d03419fbb..4f9a70a85 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -250,6 +250,9 @@ Release Date: Not Released
 	 -  Removed previously deprecated ``sha1()`` method.
    -  Changed :doc:`Language Library <libraries/language>` method ``load()`` to filter the language name with ``ctype_digit()``.
    -  :doc:`Profiler Library <general/profiling>` now also displays database object names.
+   -  :doc:`Migration Library <libraries/migration>` changes include:
+     -  Added support for timestamp-based migrations (enabled by default)
+     -  Added ``$config['migration_type']`` to allow switching between sequential migrations and timestamp migrations
 
 -  Core
 
diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst
index cb7d96a6d..1a73fb78d 100644
--- a/user_guide_src/source/libraries/migration.rst
+++ b/user_guide_src/source/libraries/migration.rst
@@ -13,17 +13,40 @@ run so all you have to do is update your application files and
 call **$this->migrate->current()** to work out which migrations should be run. 
 The current version is found in **config/migration.php**.
 
+********************
+Migration file names
+********************
+
+Each Migration is run in numeric order forward or backwards depending on the
+method taken. Two numbering styles are available:
+
+* **Sequential:** each migration is numbered in sequence, starting with **001**.
+  Each number must be three digits, and there must not be any gaps in the
+  sequence. (This was the numbering scheme prior to CodeIgniter 3.0.)
+* **Timestamp:** each migration is numbered using the timestamp when the migration
+  was created, in **YYYYMMDDHHIISS** format (e.g. **20121031100537**). This
+  helps prevent numbering conflicts when working in a team environment, and is
+  the preferred scheme in CodeIgniter 3.0 and later.
+
+The desired style may be selected using the **$config['migration_type']**
+setting in your **migration.php** config file.
+
+Regardless of which numbering style you choose to use, prefix your migration
+files with the migration number followed by an underscore and a descriptive
+name for the migration. For example:
+
+* **001_add_blog.php** (sequential numbering)
+* **20121031100537_add_blog.php** (timestamp numbering)
+
 ******************
 Create a Migration
 ******************
-
-.. note:: Each Migration is run in numerical order forward or backwards 
-	depending on the method taken. Use a prefix of 3 numbers followed by an 
-	underscore for the filename of your migration.
 	
 This will be the first migration for a new site which has a blog. All 
 migrations go in the folder **application/migrations/** and have names such 
-as: **001_add_blog.php**.::
+as **20121031100537_add_blog.php**.::
+
+	<?php
 
 	defined('BASEPATH') OR exit('No direct script access allowed');
 
@@ -47,7 +70,7 @@ as: **001_add_blog.php**.::
 					'null' => TRUE,
 				),
 			));
-			
+			$this->dbforge->add_key('blog_id', TRUE);
 			$this->dbforge->create_table('blog');
 		}
 
@@ -55,6 +78,7 @@ as: **001_add_blog.php**.::
 		{
 			$this->dbforge->drop_table('blog');
 		}
+	}
 
 Then in **application/config/migration.php** set **$config['migration_version'] = 1;**.
 
@@ -65,25 +89,25 @@ Usage Example
 In this example some simple code is placed in **application/controllers/migrate.php** 
 to update the schema.::
 
-	$this->load->library('migration');
-
-	if ( ! $this->migration->current())
+	<?php
+	
+	class Migrate extends CI_Controller
 	{
-		show_error($this->migration->error_string());
+	    public function index()
+	    {
+	    	$this->load->library('migration');
+	    	
+	    	if ($this->migration->current() === FALSE)
+	    	{
+	    		show_error($this->migration->error_string());
+	    	}
+	    }
 	}
 
 ******************
 Function Reference
 ******************
 
-There are five available methods for the Migration class:
-
--  $this->migration->current();
--  $this->migration->error_string();
--  $this->migration->find_migrations();
--  $this->migration->latest();
--  $this->migration->version();
-
 $this->migration->current()
 ============================
 
@@ -124,14 +148,16 @@ Migration Preferences
 
 The following is a table of all the config options for migrations.
 
-========================== ====================== ============= =============================================
-Preference                 Default                Options       Description
-========================== ====================== ============= =============================================
-**migration_enabled**      FALSE                  TRUE / FALSE  Enable or disable migrations.
-**migration_path**         APPPATH.'migrations/'  None          The path to your migrations folder.
-**migration_version**      0                      None          The current version your database should use.
-**migration_table**        migrations             None          The table name for storing the shema
-                                                                version number.
-**migration_auto_latest**  FALSE                  TRUE / FALSE  Enable or disable automatically 
-                                                                running migrations.
-========================== ====================== ============= =============================================
+========================== ====================== ========================== =============================================
+Preference                 Default                Options                    Description
+========================== ====================== ========================== =============================================
+**migration_enabled**      FALSE                  TRUE / FALSE               Enable or disable migrations.
+**migration_path**         APPPATH.'migrations/'  None                       The path to your migrations folder.
+**migration_version**      0                      None                       The current version your database should use.
+**migration_table**        migrations             None                       The table name for storing the schema
+                                                                             version number.
+**migration_auto_latest**  FALSE                  TRUE / FALSE               Enable or disable automatically 
+                                                                             running migrations.
+**migration_type**        'timestamp'            'timestamp' / 'sequential' The type of numeric identifier used to name
+                                                                             migration files.
+========================== ====================== ========================== =============================================