Update (21st October, 2012): As Phinx 0.1.4 has now shipped, I have updated this tutorial to work with Composer instead of PEAR.

Earlier this year I decided to open-source one of my personal software projects Phinx. Phinx is a database migration tool (think Ruby on Rails ActiveRecord migrations) where can you describe all of your database transformations in pure PHP. I have used this tool for many of my consulting projects, however it still took a lot of effort to turn it into a re-usable product. In this tutorial I'm going to explain how to install Phinx and use it with a simple guestbook application.

This tutorial assumes you have working knowledge of PHP, the Composer dependency manager, Zend Framework 1.x and the MySQL database. You should have a copy of Zend Framework 1.x available in your PHP include path. I have coded the sample application against ZF 1.11.11. It is also assumed you are able to configure your webserver to run the sample application. I have used Mac OS X to develop this tutorial.

I have a sample Guestbook application available on GitHub. Start by cloning the application:

Next setup your webserver to run the sample application.

Create an empty database called guestbook and open the Guestbook configuration file (application/configs/application.ini). Change the database settings to match your system. Now we are ready to start using Phinx.

First we need to install Phinx. By far the best way is via Composer as a dependency. Create an empty file called composer.json in the root of the guestbook application. Now open this file and change it to look like the following:

gist:robmorgan/3925059#composer.json

Now run Composer to install Phinx as a dependency:

Phinx will now be available under the vendor/bin/phinx command.

Phinx uses a configuration file (phinx.yml) in the root of your project to learn about it's migrations. The configuration file is a simple YAML-based file. More information is available on the official Phinx documentation site: http://docs.phinx.org/en/latest/configuration.html.

To Phinx-ify your app, simply run:

Phinx will create a configuration file with a few defaults, open this file in your text editor. A great feature of Phinx is that it supports multiple environments, by default the development environment is enabled. Edit the development environment settings to match your configuration.

Next we need to create a directory to store the migrations. Unless specified otherwise Phinx expects a directory called migrations in your project root directory:

Now execute the status command to test your database connection.

Phinx will attempt to connect to your default environment database. If a successful connection is made, then Phinx will create an empty table to store the migration history.

Our sample application is a guestbook. We need to create a table to store the posts. For each post I want to be able to enter a title, message and save the time that it was created. Let's create a new migration called CreatePostsTable:

Phinx will create an empty migration file in the migrations directory. Open this file in your text editor. In the up method we will use the Table API to create a new database table. Next in the down method we will simply remove this table. By specifying the reverse of our transformations in the down method we are able to use Phinx's rollback functionality. It is important to note that Phinx creates an id column by default for every table. More information about this column is available in the Phinx documentation. Your migration file should look like this:

gist:robmorgan/3883258#20121013151612_create_posts_table.php

Now it's time to execute our newly created database migration. Run Phinx with the migrate command:

Phinx will connect to your database and execute the CreatePostsTable migration. Now you have successfully migrated your database to the latest version. Therefore we can now use the Guestbook application:

And that's it!

There we have a brief introduction to getting started with Phinx. You can find out more about the project on it's website here: https://phinx.org. We are also looking for contributors to close bugs, add features and work on the documentation. If you'd like to help checkout the GitHub project here: https://github.com/robmorgan/phinx.