Getting Started With Phinx

14 October 2012

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.

Prerequisites

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.

Installation

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:

	{
	"require": {
	"robmorgan/phinx": "*"
	}
	}

view raw composer.json hosted with ❤ by GitHub

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:

	<?php

	use Phinx\Migration\AbstractMigration;

	class CreatePostsTable extends AbstractMigration
	{
	/**
	* Migrate Up.
	*/
	public function up()
	{
	$posts = $this->table('posts');
	$posts->addColumn('title', 'string', array('limit' => 40))
	->addColumn('body', 'text')
	->addColumn('created', 'datetime')
	->save();
	}

	/**
	* Migrate Down.
	*/
	public function down()
	{
	$this->dropTable('posts');
	}
	}

view raw 20121013151612_create_posts_table.php hosted with ❤ by GitHub

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!

Conclusion

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.

Rob Morgan

Australian Startup CTO, Berlin Alumni, Creator of Phinx, Startups, Technology, Travel