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.
Setup the Sample Application
I have a sample Guestbook application available on GitHub. Start by cloning the application:
$ git clone https://github.com/robmorgan/guestbook-tutorial
Next setup your webserver to run the sample application.
Configure your Database
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:
Now run Composer to install Phinx as a dependency:
$ curl -s https://getcomposer.org/installer | php $ php composer.phar install
Phinx will now be available under the vendor/bin/phinx command.
Making Phinx work with the Sample Application
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:
$ php vendor/bin/phinx init
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:
$ mkdir migrations
Now execute the status command to test your database connection.
$ php vendor/bin/phinx status
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.
Creating Your First Migration
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:
$ php vendor/bin/phinx create CreatePostsTable Phinx by Rob Morgan. version 0.1.4 using config ./phinx.yml using migration path /Users/robbym/Sites/guestbook/migrations created ./migrations/20121013151612_create_posts_table.php
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:
Transforming the Database
Now it’s time to execute our newly created database migration. Run Phinx with the migrate command:
$ php vendor/bin/phinx migrate Phinx by Rob Morgan. version 0.1.4 using config ./phinx.yml using migration path /Users/robbym/Sites/guestbook/migrations warning no environment specified, defaulting to: development using adapter mysql == 20121013151612 CreatePostsTable migrating == 20121013151612 CreatePostsTable migrated 1.1352s All Done. Took 1.1485s
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: http://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: http://github.com/robmorgan/phinx.