Add a migration system (#2760)

* Add a Minz_Migrator class

Until now, we updated the database structure somewhere in the code but
it wasn't always consistent and somehow complicated to find. Also, this
code was always checked for nothing.

The Migrator aims to improve and ease the creation of migrations. It
should improve the way we apply the updates, making the update server
almost useless.

References:

- example of migration (before Migrator): https://github.com/FreshRSS/FreshRSS/commit/cc0db9af4f980829faa4bf0960617807b32fb4fa#diff-11a53443fa81512b128c66b065df0679R10
- update server: https://github.com/FreshRSS/update.freshrss.org
- PR moving the code of the update server to the core: https://github.com/FreshRSS/FreshRSS/pull/1760

* Automatically apply migrations

For now, administrators are used to have nothing to do during an update
else than getting the new code. I suggest to keep this behaviour and
automatically apply migrations if we detect new ones.

Another solution would be to create a CLI command and ask admins to call
it after getting the new code. It could hide migrations errors to end
users, but admin can forget to apply migrations since there are not used
to it.

* Add documentation for Minz Migrator

* Execute migrations even if next ones are applied

* Change mechanism to prevent multiple update at once

* Use mkdir to create the lock and to test it exists

Reference: https://stackoverflow.com/a/731634

* Append .lock to applied_migrations_path

There are no needs to define another file to serve as a lock.

* Change migrations naming convention

* Apply suggestions from code review

Co-Authored-By: Alexandre Alapetite <alexandre@alapetite.fr>

* Perform a low-cost migration versions comparaison

* Clarify version numbers concerning the migration system

Co-authored-by: Alexandre Alapetite <alexandre@alapetite.fr>

app/install.php

@@ -674,7 +674,7 @@ case 3:
 case 4:
 	break;
 case 5:
-	if (deleteInstall()) {
+	if (setupMigrations() && deleteInstall()) {
 		header('Location: index.php');
 	}
 	break;

cli/do-install.php

@@ -109,6 +109,10 @@ echo '• Remember to create the default user: ', $config['default_user'] , "\n"
 
 accessRights();
 
+if (!setupMigrations()) {
+	fail('FreshRSS access right problem while creating migrations version file!');
+}
+
 if (!deleteInstall()) {
 	fail('FreshRSS access right problem while deleting install file!');
 }

constants.php

@@ -6,6 +6,8 @@ define('FRESHRSS_VERSION', '1.16.3-dev');
 define('FRESHRSS_WEBSITE', 'https://freshrss.org');
 define('FRESHRSS_WIKI', 'https://freshrss.github.io/FreshRSS/');
 
+define('APP_NAME', 'FreshRSS');
+
 define('FRESHRSS_PATH', __DIR__);
 define('PUBLIC_PATH', FRESHRSS_PATH . '/p');
 define('PUBLIC_TO_INDEX_PATH', '/i');
@@ -14,6 +16,7 @@ define('PUBLIC_RELATIVE', '..');
 define('LIB_PATH', FRESHRSS_PATH . '/lib');
 define('APP_PATH', FRESHRSS_PATH . '/app');
 define('CORE_EXTENSIONS_PATH', LIB_PATH . '/core-extensions');
+define('TESTS_PATH', FRESHRSS_PATH . '/tests');
 //</Not customisable>
 
 function safe_define($name, $value) {

data/.gitignore

@@ -8,3 +8,5 @@ no-cache.txt
 update.php
 tos.html
 opml.xml
+applied_migrations.txt
+applied_migrations.txt.lock

docs/en/developers/01_First_steps.md

@@ -57,7 +57,7 @@ The `TAG` variable can be anything (e.g. `local`). You can target a specific arc
 
 # Project architecture
 
-**TODO**
+- the PHP framework: [Minz](Minz/index.md)
 
 # Extensions
 

docs/en/developers/03_Backend/02_Minz.md

@@ -1,27 +0,0 @@
-# Models
-
-**TODO**
-
-# Controllers and actions
-
-**TODO**
-
-# Views
-
-**TODO**
-
-# Routing
-
-**TODO**
-
-# Writing URL
-
-**TODO**
-
-# Internationalisation
-
-**TODO**
-
-# Understanding internals
-
-**TODO**

docs/en/developers/Minz/index.md

@@ -0,0 +1,19 @@
+# Minz
+
+Minz is the homemade PHP framework used by FreshRSS.
+
+The documentation is still incomplete and it would be great to explain:
+
+- routing, controllers and actions
+- configuration
+- models and database
+- views
+- URLs management
+- sessions
+- internationalisation
+- extensions
+- mailer
+
+Existing documentation includes:
+
+- [How to manage migrations](migrations.md)

docs/en/developers/Minz/migrations.md

@@ -0,0 +1,39 @@
+# How to manage migrations with Minz
+
+Migrations are the way to modify the database or the structure of files under the `data/` path.
+
+## How to write a migration?
+
+Migrations are placed under the `app/migrations` folder.
+
+Good practice is to prepend the filename by the current date and explain what does the migration do in few words (e.g. `2020_01_11_CreateFooTable.php`).
+
+The files must contain a class which name starts with `FreshRSS_Migration_`, followed by the basename of the file (e.g. `FreshRSS_Migration_2020_01_11_CreateFooTable`).
+
+The class must declare a `migrate` static function. It must return `true` or a string to indicate the migration is applied, or `false` otherwise. It can also raise an exception: the message will be used to detail the error.
+
+Example:
+
+```php
+// File: app/migrations/2020_01_11_CreateFooTable.php
+class FreshRSS_Migration_2020_01_11_CreateFooTable {
+	public static function migrate() {
+		$pdo = new MinzPDOSQLite('sqlite:/some/path/db.sqlite');
+		$result = $pdo->exec('CREATE TABLE foos (bar TEXT)');
+		if ($result === false) {
+			$error = $pdo->errorInfo();
+			raise Exception('Error in SQL statement: ' . $error[2]);
+		}
+
+		return true;
+	}
+}
+```
+
+## How to apply migrations?
+
+They are automatically applied one by one when a user accesses FreshRSS.
+
+Before being applied, migrations are sorted by filenames (see the [`strnatcmp`](https://php.net/strnatcmp) function). Already applied migrations are skipped (the list can be found in the `data/applied_migrations.txt` file).
+
+To ensure migrations are not applied several times if two users access FreshRSS at the same time, a folder named `data/applied_migrations.txt.lock` is created, then deleted at the end of the process.

lib/Minz/Migrator.php

@@ -0,0 +1,285 @@
+<?php
+
+/**
+ * The Minz_Migrator helps to migrate data (in a database or not) or the
+ * architecture of a Minz application.
+ *
+ * @author Marien Fressinaud <dev@marienfressinaud.fr>
+ * @license http://www.gnu.org/licenses/agpl-3.0.en.html AGPL
+ */
+class Minz_Migrator
+{
+	/** @var string[] */
+	private $applied_versions;
+
+	/** @var array */
+	private $migrations = [];
+
+	/**
+	 * Execute a list of migrations, skipping versions indicated in a file
+	 *
+	 * @param string $migrations_path
+	 * @param string $applied_migrations_path
+	 *
+	 * @throws BadFunctionCallException if a callback isn't callable.
+	 * @throws DomainException if there is no migrations corresponding to the
+	 *                         given version (can happen if version file has
+	 *                         been modified, or migrations path cannot be
+	 *                         read).
+	 *
+	 * @return boolean|string Returns true if execute succeeds to apply
+	 *                        migrations, or a string if it fails.
+	 */
+	public static function execute($migrations_path, $applied_migrations_path) {
+		$applied_migrations = @file_get_contents($applied_migrations_path);
+		if ($applied_migrations === false) {
+			return "Cannot open the {$applied_migrations_path} file";
+		}
+		$applied_migrations = array_filter(explode("\n", $applied_migrations));
+
+		$migration_files = scandir($migrations_path);
+		$migration_files = array_filter($migration_files, function ($filename) {
+			return $filename[0] !== '.';
+		});
+		$migration_versions = array_map(function ($filename) {
+			return basename($filename, '.php');
+		}, $migration_files);
+
+		// We apply a "low-cost" comparaison to avoid to include the migration
+		// files at each run. It is equivalent to the upToDate method.
+		if (count($applied_migrations) === count($migration_versions) &&
+			empty(array_diff($applied_migrations, $migration_versions))) {
+			// already at the latest version, so there is nothing more to do
+			return true;
+		}
+
+		$lock_path = $applied_migrations_path . '.lock';
+		if (!@mkdir($lock_path)) {
+			// Someone is probably already executing the migrations (the folder
+			// already exists).
+			// We should probably return something else, but we don't want the
+			// user to think there is an error (it's normal workflow), so let's
+			// stick to this solution for now.
+			// Another option would be to show him a maintenance page.
+			Minz_Log::warning(
+				'A request has been served while the application wasn’t up-to-date. '
+				. 'Too many of these errors probably means a previous migration failed.'
+			);
+			return true;
+		}
+
+		$migrator = new self($migrations_path);
+		if ($applied_migrations) {
+			$migrator->setAppliedVersions($applied_migrations);
+		}
+		$results = $migrator->migrate();
+
+		foreach ($results as $migration => $result) {
+			if ($result === true) {
+				$result = 'OK';
+			} elseif ($result === false) {
+				$result = 'KO';
+			}
+
+			Minz_Log::notice("Migration {$migration}: {$result}");
+		}
+
+		$applied_versions = implode("\n", $migrator->appliedVersions());
+		$saved = file_put_contents($applied_migrations_path, $applied_versions);
+
+		if (!@rmdir($lock_path)) {
+			Minz_Log::error(
+				'We weren’t able to unlink the migration executing folder, '
+				. 'you might want to delete yourself: ' . $lock_path
+			);
+			// we don't return early because the migrations could have been
+			// applied successfully. This file is not "critical" if not removed
+			// and more errors will eventually appear in the logs.
+		}
+
+		if ($saved === false) {
+			return "Cannot save the {$applied_migrations_path} file";
+		}
+
+		if (!$migrator->upToDate()) {
+			// still not up to date? It means last migration failed.
+			return 'A migration failed to be applied, please see previous logs';
+		}
+
+		return true;
+	}
+
+	/**
+	 * Create a Minz_Migrator instance. If directory is given, it'll load the
+	 * migrations from it.
+	 *
+	 * All the files in the directory must declare a class named
+	 * <app_name>_Migration_<filename> with a static `migrate` method.
+	 *
+	 * - <app_name> is the application name declared in the APP_NAME constant
+	 * - <filename> is the migration file name, without the `.php` extension
+	 *
+	 * The files starting with a dot are ignored.
+	 *
+	 * @param string|null $directory
+	 *
+	 * @throws BadFunctionCallException if a callback isn't callable (i.e.
+	 *                                  cannot call a migrate method).
+	 */
+	public function __construct($directory = null)
+	{
+		$this->applied_versions = [];
+
+		if (!is_dir($directory)) {
+			return;
+		}
+
+		foreach (scandir($directory) as $filename) {
+			if ($filename[0] === '.') {
+				continue;
+			}
+
+			$filepath = $directory . '/' . $filename;
+			$migration_version = basename($filename, '.php');
+			$migration_class = APP_NAME . "_Migration_" . $migration_version;
+			$migration_callback = $migration_class . '::migrate';
+
+			$include_result = @include_once($filepath);
+			if (!$include_result) {
+				Minz_Log::error(
+					"{$filepath} migration file cannot be loaded.",
+					ADMIN_LOG
+				);
+			}
+			$this->addMigration($migration_version, $migration_callback);
+		}
+	}
+
+	/**
+	 * Register a migration into the migration system.
+	 *
+	 * @param string $version The version of the migration (be careful, migrations
+	 *                        are sorted with the `strnatcmp` function)
+	 * @param callback $callback The migration function to execute, it should
+	 *                           return true on success and must return false
+	 *                           on error
+	 *
+	 * @throws BadFunctionCallException if the callback isn't callable.
+	 */
+	public function addMigration($version, $callback)
+	{
+		if (!is_callable($callback)) {
+			throw new BadFunctionCallException("{$version} migration cannot be called.");
+		}
+
+		$this->migrations[$version] = $callback;
+	}
+
+	/**
+	 * Return the list of migrations, sorted with `strnatcmp`
+	 *
+	 * @see https://www.php.net/manual/en/function.strnatcmp.php
+	 *
+	 * @return array
+	 */
+	public function migrations()
+	{
+		$migrations = $this->migrations;
+		uksort($migrations, 'strnatcmp');
+		return $migrations;
+	}
+
+	/**
+	 * Set the applied versions of the application.
+	 *
+	 * @param string[] $applied_versions
+	 *
+	 * @throws DomainException if there is no migrations corresponding to a version
+	 */
+	public function setAppliedVersions($versions)
+	{
+		foreach ($versions as $version) {
+			$version = trim($version);
+			if (!isset($this->migrations[$version])) {
+				throw new DomainException("{$version} migration does not exist.");
+			}
+			$this->applied_versions[] = $version;
+		}
+	}
+
+	/**
+	 * @return string[]
+	 */
+	public function appliedVersions()
+	{
+		$versions = $this->applied_versions;
+		usort($versions, 'strnatcmp');
+		return $versions;
+	}
+
+	/**
+	 * Return the list of available versions, sorted with `strnatcmp`
+	 *
+	 * @see https://www.php.net/manual/en/function.strnatcmp.php
+	 *
+	 * @return string[]
+	 */
+	public function versions()
+	{
+		$migrations = $this->migrations();
+		return array_keys($migrations);
+	}
+
+	/**
+	 * @return boolean Return true if the application is up-to-date, false
+	 *                 otherwise. If no migrations are registered, it always
+	 *                 returns true.
+	 */
+	public function upToDate()
+	{
+		// Counting versions is enough since we cannot apply a version which
+		// doesn't exist (see setAppliedVersions method).
+		return count($this->versions()) === count($this->applied_versions);
+	}
+
+	/**
+	 * Migrate the system to the latest version.
+	 *
+	 * It only executes migrations AFTER the current version. If a migration
+	 * returns false or fails, it immediatly stops the process.
+	 *
+	 * If the migration doesn't return false nor raise an exception, it is
+	 * considered as successful. It is considered as good practice to return
+	 * true on success though.
+	 *
+	 * @return array Return the results of each executed migration. If an
+	 *               exception was raised in a migration, its result is set to
+	 *               the exception message.
+	 */
+	public function migrate()
+	{
+		$result = [];
+		foreach ($this->migrations() as $version => $callback) {
+			if (in_array($version, $this->applied_versions)) {
+				// the version is already applied so we skip this migration
+				continue;
+			}
+
+			try {
+				$migration_result = $callback();
+				$result[$version] = $migration_result;
+			} catch (Exception $e) {
+				$migration_result = false;
+				$result[$version] = $e->getMessage();
+			}
+
+			if ($migration_result === false) {
+				break;
+			}
+
+			$this->applied_versions[] = $version;
+		}
+
+		return $result;
+	}
+}

lib/lib_install.php

@@ -120,3 +120,12 @@ function deleteInstall() {
 	@unlink($path);
 	return !file_exists($path);
 }
+
+function setupMigrations() {
+	$migrations_path = APP_PATH . '/migrations';
+	$migrations_version_path = DATA_PATH . '/applied_migrations.txt';
+
+	$migrator = new Minz_Migrator($migrations_path);
+	$versions = implode("\n", $migrator->versions());
+	return @file_put_contents($migrations_version_path, $versions);
+}

p/i/index.php

@@ -42,14 +42,43 @@ if (file_exists(DATA_PATH . '/do-install.txt')) {
 		}
 	}
 
+	$migrations_path = APP_PATH . '/migrations';
+	$applied_migrations_path = DATA_PATH . '/applied_migrations.txt';
+
+	// The next line is temporary: the migrate method expects the applied_migrations.txt
+	// file to exist. This is because the install script creates this file, so
+	// if it is missing, it means the application is not installed. But we
+	// should also take care of applications installed before the new
+	// migrations system (<=1.16). Indeed, they are installed but the migrations
+	// version file doesn't exist. So for now (1.17), we continue to check if the
+	// application is installed with the do-install.txt file: if yes, we create
+	// the version file. Starting from version 1.18, all the installed systems
+	// will have the file and so we will be able to remove this temporary line
+	// and stop using the do-install.txt file to check if FRSS is already
+	// installed.
+	touch($applied_migrations_path);
+
+	$error = false;
 	try {
-		$front_controller = new FreshRSS();
-		$front_controller->init();
-		$front_controller->run();
+		// Apply the migrations if any
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+		if ($result === true) {
+			$front_controller = new FreshRSS();
+			$front_controller->init();
+			$front_controller->run();
+		} else {
+			$error = $result;
+		}
 	} catch (Exception $e) {
+		$error = $e->getMessage();
+	}
+
+	if ($error) {
+		// TODO this should be definitely improved to display a nicer error
+		// page to the users (especially non administrators).
 		echo '### Fatal error! ###<br />', "\n";
-		Minz_Log::error($e->getMessage());
+		Minz_Log::error($error);
 		echo 'See logs files.';
-		syslog(LOG_INFO, 'FreshRSS Fatal error! ' . $e->getMessage());
+		syslog(LOG_INFO, 'FreshRSS Fatal error! ' . $error);
 	}
 }

tests/bootstrap.php

@@ -3,5 +3,7 @@
 error_reporting(E_ALL);
 ini_set('display_errors', 1);
 
+define('COPY_LOG_TO_SYSLOG', false);
+
 require(__DIR__ . '/../constants.php');
 require(LIB_PATH . '/lib_rss.php');	//Includes class autoloader

tests/fixtures/migrations/2019_12_22_FooBar.php

@@ -0,0 +1,10 @@
+<?php
+
+class FreshRSS_Migration_2019_12_22_FooBar {
+	/**
+	 * @return boolean true if the migration was successful, false otherwise
+	 */
+	public static function migrate() {
+		return true;
+	}
+}

tests/fixtures/migrations/2019_12_23_Baz.php

@@ -0,0 +1,10 @@
+<?php
+
+class FreshRSS_Migration_2019_12_23_Baz {
+	/**
+	 * @return boolean true if the migration was successful, false otherwise
+	 */
+	public static function migrate() {
+		return true;
+	}
+}

tests/fixtures/migrations_with_failing/2020_01_11_FooBar.php

@@ -0,0 +1,10 @@
+<?php
+
+class FreshRSS_Migration_2020_01_11_FooBar {
+	/**
+	 * @return boolean true if the migration was successful, false otherwise
+	 */
+	public static function migrate() {
+		return true;
+	}
+}

tests/fixtures/migrations_with_failing/2020_01_12_Baz.php

@@ -0,0 +1,10 @@
+<?php
+
+class FreshRSS_Migration_2020_01_12_Baz {
+	/**
+	 * @return boolean true if the migration was successful, false otherwise
+	 */
+	public static function migrate() {
+		return false;
+	}
+}

tests/lib/Minz/MigratorTest.php

@@ -0,0 +1,321 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+class Minz_MigratorTest extends TestCase
+{
+	public function testAddMigration() {
+		$migrator = new Minz_Migrator();
+
+		$migrator->addMigration('foo', function () {
+			return true;
+		});
+
+		$migrations = $migrator->migrations();
+		$this->assertArrayHasKey('foo', $migrations);
+		$result = $migrations['foo']();
+		$this->assertTrue($result);
+	}
+
+	public function testAddMigrationFailsIfUncallableMigration() {
+		$this->expectException(BadFunctionCallException::class);
+		$this->expectExceptionMessage('foo migration cannot be called.');
+
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', null);
+	}
+
+	public function testMigrationsIsSorted() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('2_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('10_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('1_foo', function () {
+			return true;
+		});
+		$expected_versions = ['1_foo', '2_foo', '10_foo'];
+
+		$migrations = $migrator->migrations();
+
+		$this->assertSame($expected_versions, array_keys($migrations));
+	}
+
+	public function testSetAppliedVersions() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', function () {
+			return true;
+		});
+
+		$migrator->setAppliedVersions(['foo']);
+
+		$this->assertSame(['foo'], $migrator->appliedVersions());
+	}
+
+	public function testSetAppliedVersionsTrimArgument() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', function () {
+			return true;
+		});
+
+		$migrator->setAppliedVersions(["foo\n"]);
+
+		$this->assertSame(['foo'], $migrator->appliedVersions());
+	}
+
+	public function testSetAppliedVersionsFailsIfMigrationDoesNotExist() {
+		$this->expectException(DomainException::class);
+		$this->expectExceptionMessage('foo migration does not exist.');
+
+		$migrator = new Minz_Migrator();
+
+		$migrator->setAppliedVersions(['foo']);
+	}
+
+	public function testVersions() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', function () {
+			return true;
+		});
+		$migrator->addMigration('bar', function () {
+			return true;
+		});
+
+		$versions = $migrator->versions();
+
+		$this->assertSame(['bar', 'foo'], $versions);
+	}
+
+	public function testMigrate() {
+		$migrator = new Minz_Migrator();
+		$spy = false;
+		$migrator->addMigration('foo', function () use (&$spy) {
+			$spy = true;
+			return true;
+		});
+		$this->assertEmpty($migrator->appliedVersions());
+
+		$result = $migrator->migrate();
+
+		$this->assertTrue($spy);
+		$this->assertSame(['foo'], $migrator->appliedVersions());
+		$this->assertSame([
+			'foo' => true,
+		], $result);
+	}
+
+	public function testMigrateCallsMigrationsInSortedOrder() {
+		$migrator = new Minz_Migrator();
+		$spy_foo_1_is_called = false;
+		$migrator->addMigration('2_foo', function () use (&$spy_foo_1_is_called) {
+			return $spy_foo_1_is_called;
+		});
+		$migrator->addMigration('1_foo', function () use (&$spy_foo_1_is_called) {
+			$spy_foo_1_is_called = true;
+			return true;
+		});
+
+		$result = $migrator->migrate();
+
+		$this->assertSame(['1_foo', '2_foo'], $migrator->appliedVersions());
+		$this->assertSame([
+			'1_foo' => true,
+			'2_foo' => true,
+		], $result);
+	}
+
+	public function testMigrateDoesNotCallAppliedMigrations() {
+		$migrator = new Minz_Migrator();
+		$spy = false;
+		$migrator->addMigration('1_foo', function () use (&$spy) {
+			$spy = true;
+			return true;
+		});
+		$migrator->setAppliedVersions(['1_foo']);
+
+		$result = $migrator->migrate();
+
+		$this->assertFalse($spy);
+		$this->assertSame([], $result);
+	}
+
+	public function testMigrateCallNonAppliedBetweenTwoApplied() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('1_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('2_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('3_foo', function () {
+			return true;
+		});
+		$migrator->setAppliedVersions(['1_foo', '3_foo']);
+
+		$result = $migrator->migrate();
+
+		$this->assertSame(['1_foo', '2_foo', '3_foo'], $migrator->appliedVersions());
+		$this->assertSame([
+			'2_foo' => true,
+		], $result);
+	}
+
+	public function testMigrateWithMigrationReturningFalseDoesNotApplyVersion() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('1_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('2_foo', function () {
+			return false;
+		});
+
+		$result = $migrator->migrate();
+
+		$this->assertSame(['1_foo'], $migrator->appliedVersions());
+		$this->assertSame([
+			'1_foo' => true,
+			'2_foo' => false,
+		], $result);
+	}
+
+	public function testMigrateWithMigrationReturningFalseDoesNotExecuteNextMigrations() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('1_foo', function () {
+			return false;
+		});
+		$spy = false;
+		$migrator->addMigration('2_foo', function () use (&$spy) {
+			$spy = true;
+			return true;
+		});
+
+		$result = $migrator->migrate();
+
+		$this->assertEmpty($migrator->appliedVersions());
+		$this->assertFalse($spy);
+		$this->assertSame([
+			'1_foo' => false,
+		], $result);
+	}
+
+	public function testMigrateWithFailingMigration() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', function () {
+			throw new \Exception('Oops, it failed.');
+		});
+
+		$result = $migrator->migrate();
+
+		$this->assertEmpty($migrator->appliedVersions());
+		$this->assertSame([
+			'foo' => 'Oops, it failed.',
+		], $result);
+	}
+
+	public function testUpToDate() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('foo', function () {
+			return true;
+		});
+		$migrator->setAppliedVersions(['foo']);
+
+		$upToDate = $migrator->upToDate();
+
+		$this->assertTrue($upToDate);
+	}
+
+	public function testUpToDateIfRemainingMigration() {
+		$migrator = new Minz_Migrator();
+		$migrator->addMigration('1_foo', function () {
+			return true;
+		});
+		$migrator->addMigration('2_foo', function () {
+			return true;
+		});
+		$migrator->setAppliedVersions(['2_foo']);
+
+		$upToDate = $migrator->upToDate();
+
+		$this->assertFalse($upToDate);
+	}
+
+	public function testUpToDateIfNoMigrations() {
+		$migrator = new Minz_Migrator();
+
+		$upToDate = $migrator->upToDate();
+
+		$this->assertTrue($upToDate);
+	}
+
+	public function testConstructorLoadsDirectory() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations/';
+		$migrator = new Minz_Migrator($migrations_path);
+		$expected_versions = ['2019_12_22_FooBar', '2019_12_23_Baz'];
+
+		$migrations = $migrator->migrations();
+
+		$this->assertSame($expected_versions, array_keys($migrations));
+	}
+
+	public function testExecute() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations/';
+		$applied_migrations_path = tempnam('/tmp', 'applied_migrations.txt');
+
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+
+		$this->assertTrue($result);
+		$versions = file_get_contents($applied_migrations_path);
+		$this->assertSame("2019_12_22_FooBar\n2019_12_23_Baz", $versions);
+	}
+
+	public function testExecuteWithAlreadyAppliedMigration() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations/';
+		$applied_migrations_path = tempnam('/tmp', 'applied_migrations.txt');
+		file_put_contents($applied_migrations_path, '2019_12_22_FooBar');
+
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+
+		$this->assertTrue($result);
+		$versions = file_get_contents($applied_migrations_path);
+		$this->assertSame("2019_12_22_FooBar\n2019_12_23_Baz", $versions);
+	}
+
+	public function testExecuteWithAppliedMigrationInDifferentOrder() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations/';
+		$applied_migrations_path = tempnam('/tmp', 'applied_migrations.txt');
+		file_put_contents($applied_migrations_path, "2019_12_23_Baz\n2019_12_22_FooBar");
+
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+
+		$this->assertTrue($result);
+		$versions = file_get_contents($applied_migrations_path);
+		// if the order changes, it probably means the first versions comparaison
+		// test doesn't work anymore
+		$this->assertSame("2019_12_23_Baz\n2019_12_22_FooBar", $versions);
+	}
+
+	public function testExecuteFailsIfVersionPathDoesNotExist() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations/';
+		$applied_migrations_path = tempnam('/tmp', 'applied_migrations.txt');
+		$expected_result = "Cannot open the {$applied_migrations_path} file";
+		unlink($applied_migrations_path);
+
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+
+		$this->assertSame($expected_result, $result);
+	}
+
+	public function testExecuteFailsIfAMigrationIsFailing() {
+		$migrations_path = TESTS_PATH . '/fixtures/migrations_with_failing/';
+		$applied_migrations_path = tempnam('/tmp', 'applied_migrations.txt');
+		$expected_result = 'A migration failed to be applied, please see previous logs';
+
+		$result = Minz_Migrator::execute($migrations_path, $applied_migrations_path);
+
+		$this->assertSame($expected_result, $result);
+		$versions = file_get_contents($applied_migrations_path);
+		$this->assertSame('2020_01_11_FooBar', $versions);
+	}
+}