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 this command is issued it determines the next available migration file name (the first time around 001, subsequently 002, 003, etc) and creates a file like db/migrate/001_CreateUsersTable.php (it will always use the next available sequence number). 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 (e.g. from 2010 to 002 to 003, etc). 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 the 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]