softius / phig
Database migrations for PHP 5.3
Requires
- php: >=5.3.0
- symfony/console: 2.*
Requires (Dev)
- phpunit/phpunit: 3.*
This package is auto-updated.
Last update: 2024-10-14 05:22:35 UTC
README
phig provides a convenient way to perform database migrations in PHP. It is vendor and framework independent and can be used with any PDO driver or database abstraction framework like Doctrine.
The aims of phig are:
- to be database framework independent: is not necessary to have background on a particular framework or library to get started.
- provide solid migration mechanism, embeddable to any project
PHP 5.3+ is required.
Installation
phig is available on packagist. All you need is to add the following lines in your project composer.json
:
{ "require": { "softius/phig": "*@dev" } }
and install via composer:
php composer.phar install
An executable will be added under your project vendor/bin
directory. If you would like to change this setup, please refer to this guide.
Running migrations
phig provides a set of tasks which either execute pending migrations or reversed (rollback) already executed migration steps.
For instance, to execute all pending migrations run:
phig migrate
If you would like to reach a particular migration you can specified it via arguments as specified below. If ommited, all pending migrations will be executed.
phig migrate 20121230185208
This works for both upwards and downwards migrations. For instance, if target 20121230185208 is greater than the current version, this will trigger upwards migration (call up method on all migrations). On the contrary, if target 20121230185208 is less or equal than the current version, this will trigger downwards migration (call down method on all migrations). For further information on up and down methods, refer to Writing a migration section.
Rolling back
To rollback the last migration step run:
phig rollback
If you would like to undo multiple migration steps you can specify it via the step
argument:
phig rollback 5
The above will undo the last 5 migrations.
Dump execution
If you would like to view the results of any of the commands above without actually executing them, append the option --dump
. This will return usefull information about the actions planned to be carried out by the corresponding command. The following examples are all valid:
phig migrate --dump
phig migrate 20121230185208 --dump
phig rollback --dump
phig rollback 3 --dump
Writing a migration
Migrations are nothing more but classes in PHP, with the following constraints that you should be aware before starting writing code:
- All migrations must be placed in a single directory.
- Any migration class must extend the
MigratableInterface
and thus the methodsup
anddown
. Theup
method is called when executing an upwards migrations while thedown
method is called on downwards migrations and rollbacks. In other words, theup
method is called to create a change whiledown
method of the same class is called to reverse that change. - The filename of the migration is important since it is used as a reference hash for phig operations. While it is possible to use either datetime or a sequence (integer i.e. build number) or even a versioning scheme, I am suggesting to follow the datetime pattern.
Here is an example
// yourproject/migrations/20130104152443-MigrationExample.php class MigrationExample implements \Phig\MigratableInterface { public method up() { create_table('users'); } public method down() { destroy_table('users'); } }
Using PDO Drivers
The following example illustrates how PDO Migratable abstract class can be used. As you can see no database helpers are provided.
// yourproject/migrations/20130107193139-PdoMigrationExample.php class PdoMigrationExample extends \Phig\Migratable\Pdo { public method up() { $this->getConnection()->exec('CREATE TABLE users … '); } public method down() { $this->getConnection()->exec('DROP TABLE users'); } }
TODO
- Provide abstract classes for
PDO Driversand Doctrine library - Improve configuration / add section in documentation
Allow class names to be defined (and hence discovered) in migration filename i.e.20121230185208-MigrationExample
(instead of20121230185208.php
)- Support more than one migration folder
- Add more examples in section Writing a migration