Getting Started

Getting started in as few steps as possible.

• Grab the code from GitHub (git clone or a zip)
• Verify runtime requirements
  • PHP5
  • Optional, but recommended, the [http://phpunit.de/ PHPUnit framework] for running the Unit Tests.

(All of the following commands assume you have changed your working directory to the root of the framework)

• Modify config/database.inc.php and enter the appropriate information for your local database.

• All commands in the framework are prefixed with php main.php followed by the exact task name and then followed by any additional arguments. This assumes that the php binary is in your $PATH.

  • Examples:

     php main.php db:setup

     php main.php db:version

     php main.php db:migrate

• Initialize your database with the schema_info table so it can start tracking the current version. This can be done by issuing the following command:

    php main.php db:setup 

Create your first migration

Issue the command:

    php generate.php create_users_table

The second argument is user-specific and is an underscored delimited list of words which describe your migration in human parseable terms. Examples might be add_index_to_cities_table or create_orders_table or rename_expertise_column_in_users, etc. The framework does not care what the file is called, it is just for your sanity.

Every time the generator runs it creates a timestamped file of the current time. For example the above generator might create a file like db/migrate/20101103105103_CreateUsersTable.php The filename (and class name) is a camel-cased string of the same argument you issued to the command.

Then open up the newly generated file in your favorite text-editor.

The class has two methods, up() and down(). The up() method is where you perform actions to be executed as you run migrations that go up the chain of migrations - that is, all migrations that have NOT been executed against your copy of the database that are based in increasing timestamped order. The down() method is where you execute actions that should be performed as you go down the chain. In most cases in the down() method you would want to undo what you did in the up() method. That is if you create a new table in the up() method then you would want to drop it in the down() method.

In a perfect world you would be able to seamlessly issue up and down migration calls and your RDBMS would be in perfect sync. That is, you dont want to create a table in a given up() method but then not drop it because if you were to do a full up/down cycle then your RDBMS would not allow you to create the same table twice.

Execute your migrations

    php main.php db:migrate

This command will execute all migrations available, report the output and update your schema info table to the appropriate version.

For a complete example of the migration systems in action, see [CompleteExamples]