So, this lead to me wondering what LAMP versions the popular distros are using, with the help of DistroWatch, I compiled this table. It only shows the community/open source distributions, the commercials counterparts for each are usually at least a year behind, guaranteeing support but only for out of date versions.

This How To will introduce some simple database migrations to your PHP application. Ruby on Rails is a popular web application framework, that provides a method of migrating (upgrading) the applications database programatically, keeping the database schema essentially version controlled. This allows individual developers to update their working databases and the databases on testing, staging or production machines to be updated with new versions of applications. The CakePHP framework has recently developed a migrations library simliar to rails, but this article focuses on using seperate tools to run database migrations, a build tool called Phing, along with a method for creating database migrations, dbdeploy.

Install Phing

I always use the beta or release candidate of phing and for the purposes of this article I suggest you do too. The best way to download and install phing is using PEAR. This can be done on Linux or Windows assuming you have the pear script in your PATH with three shell commands.

shell> pear channel-discover pear.phing.info
shell> pear config-set preferred_state beta
shell> pear install phing/phing

Example Application structure

As an example, we’re going to develop a simple application with the following directory structure.

example/
 |-- db/
 |   `-- deltas/
 |-- deploy/
 |   `-- scripts/
 |-- library/
 `-- public/

The db directory contains sql files for using and manipulating our database and
the deploy directory contains our build scripts that set the migrations in motion. The library directory contains our application code and the public folder will contain scripts and files accessible directly from the web, but will not be the focus of this article.

Build scripts

This section shows you how to develop the build scripts that will run the database migrations. The first file we need to create is a simple configuration file and should be fairly self explanatory. The file is written as key=value, lines beginning with a # are comments. Open your editor and save the following text as deploy/build.properties.

# Property files contain key/value pairs
#key=value

# This dir must contain the local application
build.dir=../

# Credentials for the database migrations
db.host=localhost
db.user=user
db.pass=password
db.name=example

# paths to programs
progs.mysql=/usr/bin/mysql

The next file we are going to create is the deploy/build.xml file. This is the file that tells Phing what we want it to do. I’m not going to go into too much detail describing each part of the build file, there are some comments, but you should consult the Phing Documentation for further details and enhancements.

<?xml version="1.0" ?>
<project name="PurpleMonkey" basedir="." default="build">

    <!-- Sets the DSTAMP, TSTAMP and TODAY properties -->
    <tstamp/>

    <!-- Load our configuration -->
    <property file="./build.properties" />

    <!-- create our migration task -->
    <target name="migrate" description="Database Migrations">  

        <!-- load the dbdeploy task -->
        <taskdef name="dbdeploy" classname="phing.tasks.ext.dbdeploy.DbDeployTask"/>

        <!-- these two filenames will contain the generated SQL to do the deploy and roll it back-->
        <property name="build.dbdeploy.deployfile" value="deploy/scripts/deploy-${DSTAMP}${TSTAMP}.sql" />
        <property name="build.dbdeploy.undofile" value="deploy/scripts/undo-${DSTAMP}${TSTAMP}.sql" />

        <!-- generate the deployment scripts -->
        <dbdeploy
            url="mysql:host=${db.host};dbname=${db.name}"
            userid="${db.user}"
            password="${db.pass}"
            dir="${build.dir}/db/deltas"
            outputfile="${build.dir}/${build.dbdeploy.deployfile}"
            undooutputfile="${build.dir}/${build.dbdeploy.undofile}" />

        <!-- execute the SQL - Use mysql command line to avoid trouble with large files or many statements and PDO -->
        <exec
            command="${progs.mysql} -h${db.host} -u${db.user} -p${db.pass} ${db.name} &lt; ${build.dbdeploy.deployfile}"
            dir="${build.dir}"
            checkreturn="true" />
    </target>
</project>

That’s essentially all the magic we need. Now we just need to create our database.

Writing dbdeploy delta scripts

We haven’t actually created our database, so rather than create it the traditional way, we will actually use the migrations to create the initial schema. We’ve not actually decided what our example application does yet, but seeing as most tutorials make blogs, why don’t we give that a bash. We’ll start simple, one table with three columns called post.

Dbdeploy works by creating numbered delta files. Each delta files contains simple SQL to both deploy the change and roll it back. The basic layout of a delta file is like so.

--//

-- Run SQL to do the changes

--//@UNDO

-- RUN SQL to undo the changes

--//

We are creating our initial schema, so put the following content in db/deltas/1-create_initial_schema.sql

--//

CREATE TABLE `post` (
    `title` VARCHAR(255),
    `time_created` DATETIME,
    `content` MEDIUMTEXT
);

--//@UNDO

DROP TABLE `post`;

--//

Migrating the database

We are one step away from running our first migration. To keep track of the current version of the database, dbdeploy requires a table in the database. This is the only time we will have to interact with the mysql client directly.

shell> mysql -hlocalhost -uroot -ppassword example
mysql> CREATE TABLE changelog (
  change_number BIGINT NOT NULL,
  delta_set VARCHAR(10) NOT NULL,
  start_dt TIMESTAMP NOT NULL,
  complete_dt TIMESTAMP NULL,
  applied_by VARCHAR(100) NOT NULL,
  description VARCHAR(500) NOT NULL
);
mysql> ALTER TABLE changelog ADD CONSTRAINT Pkchangelog PRIMARY KEY (change_number, delta_set);

We are now ready to run our first migration and create the initial schema for our application.

shell>cd deploy
shell>phing migrate

All being well, we now have a posts table in our database. But what about an author for our blog posts? We’ll have to add another table and a foreign key from the post table to author table. To do this we create another delta, we call this one db/deltas/2-create_author_and_link_to_post.sql

--//

CREATE TABLE `author` (
    `author_id` INT(10) unsigned auto_increment,
    `name` VARCHAR(255),
    PRIMARY KEY (`author_id`)
);

ALTER TABLE `post` ADD `author_id` INT(10) unsigned NULL;

--//@UNDO

ALTER TABLE `post` DROP `author_id`;

DROP TABLE `author`;

--//

Run our migrations again.

shell> cd deploy
shell> phing migrate

Conclusion

That’s pretty much it, you’ve seen how to create database deltas and use them to migrate your database, if you can’t be bothered to copy and paste things to try for yourself, download the example application.

There are plenty of caveats when it comes to version controlling databases, especially if you branch and merge your application code, some are detailed in the dbdeploy documentation

This tutorial is probably incomplete or wrong in plenty of ways, if you think you have something to point out, please leave your comments below

find . -type f -name "*.php" -exec php -l {} \; | grep -v 'No syntax errors'

For those not familiar with the programs used, it basically reads as…. Find all files that end in ‘.php’ and with each of those files run php -l. This is then put through a pipe to the grep -v, which filters out all files that are syntactically correct.

I chose Ubuntu mainly because I run Debian on my dedicated servers and am already familiar with the package management, but also because I wanted to see what the fuss is a bout. I’m very pleased so far. I’m running Mozilla Firefox, Mozilla Thunderbird, GNUCash, OpenOffice.org, Amarok and KTorrent day to day, the latter two despite using GNOME for my desktop.

Thanks to my self and this little script, I can open a ‘windows explorer window here’ from within cygwin.

#! /bin/bash
PWD=`pwd`
PATH=`cygpath -w $PWD`
/cygdrive/c/WINDOWS/explorer.exe $PATH

Now I’m not extremely well versed with patterns and so on, but I have a decent understanding of the MVC style architecture that seems to be popular these days and I’ve seen a few tutorials on Symfony, a PHP 5 web framework which I believe is fairly similar in nature to Rails, so I figured I’d get along okay. I feel I was pretty right, in a few hours over today and yesterday I’ve come out with a working database driven website and administration area running on Ruby on Rails.

Running Gentoo, I always try and use the portage package management tool, to be double sure on what I needed to do I had a little search on google which led me to this page, and these commands.

echo "dev-ruby/rails mysql fastcgi" >> /etc/portage/package.use
emerge -av rails
rails /path/to/app

That all went well and I was sat looking at a clean rails application. I fired up the builtin webserver, WEBrick, it worked, so I closed it again. Seeing as I use Apache on all my servers, I wanted to use it for the development aswell. I’ve never used FastCGI before, but what do you know there was an example virtual host definition in the rails README file.

  <VirtualHost *:80>
    ServerName rails
    DocumentRoot /path/application/public/
    ErrorLog /path/application/log/server.log

    <Directory /path/application/public/>
      Options ExecCGI FollowSymLinks
      AllowOverride all
      Allow from all
      Order allow,deny
    </Directory>
  </VirtualHost>

Once again, this worked a treat. I then set about creating my application, which by enlarge went along without many flaws, using a combination of the excellent Rails API, this Create a weblog in 15 minutes screencast and Rolling with Ruby on Rails as guidance. The biggest problem I had was creating initially trying to create the scaffolds. Not knowing RoR’s naming conventions, I’d foolishly named my database tables in the singular form, ie provider rather than providers. After overcoming this, I rolled on pretty nicely.

Using this page as guidance I used the login_generator to create a simple admin area, and the scaffolding stuff filled most of the admin pages for me, just a few tweaks here and there were required. The public face was even easier, basically allowing a few different ways to filter the list of broadband packages through one action, ‘list’.

As far as the language Ruby itself goes, I’ve barely learnt anything, basically because Rails does it all for me. The most complicated things I did code wise, was using a case statement to change the filtering on the public packages page and this simple function for turning bytes into a more readable form.

        def human_readable(number)
                count = 0
                while number/1024 > 1
                        number = number/1024
                        count += 1
                end

                iec = ['', 'K', 'M', 'G', 'T']
                return number.to_s + iec[count]
        end

My only gripe with this so far, is the speed. It does take forever to generate these simple pages, the built in webserver does seem to be a shade quicker, but I’d still rather use apache. I’m sure there’ll be some tweaks I can make to speed the FastCGI module up, but there’s no rush for that now.

Hopefully I’ll signup for a few affiliate programs and launch the site properly within the next few days, I don’t expect to make a fortune but it’s been a good little learning utility so far and I hope to use it to learn a few things about affiliate marketing.

First off is some modifications to the CGIProxy script, thanks to the guys over at Proxy Society. It basically allows me to control which type of files can be accessed through the proxy, based on the file extension.

I did have Squid running as a httpd accelerator for a while, but in the end I decided that the benefits were not really worth the hassle. On the other hand, I can see where this type of setup could prove very useful, particularly with other CGI scripts, just not proxy one’s.

I also started rotating the cgi-bin folder by adding a random number to the end, changing all the configuration scripts and the index page of the site every two hours. This certainly stopped a lot of hotlinking, but stopped people from adding favourites through the site and also any incoming traffic from Proxy.org. I also tried using apache to deny any requests without referers, this worked well for a short time…

The site had some major downtime recently and although I’m not entirely sure I think I figured out what happened. About three days ago, I had a massive influx of traffic, which ended with me serving thousands of 403 denied requests, which culminated in the proxy not being able to handle any real requests because apache and the proxy itself were firing that many 403’s back. I personally think these requests were mainly coming from China. Pages like this providing links to FreeBSD and not to mention all the forum pages hotlinking porn, are just abusing the site and it’s not fair on me or the genuine users. First I thought about geotargetting and deny requests, but that wouldn’t help anyway. A 403 might cost me 1kB, which doesn’t sound like much, but times that by thousands and my server would be crippled again. So why not drop it before it gets to Apache? A quick google search not only led me to sites listing chinese and korean ‘A’ class network ranges, but also to iptables scripts set to drop all traffic for them. Changed the port from SMTP to HTTP and I was in business. Even implemented this at work for our SMTP server, cut the spam in half!

Add to that some more links, a news page, a links page and a little bit of promotion here and there and that’s DaveProxy as of now.

Ctags generates an index (or tag) file of language objects found in source files that allows these items to be quickly and easily located by a text editor or other utility. A tag signifies a language object for which an index entry is available (or, alternatively, the index entry created for that object).

To use CTAGS with PHP 5, I downloaded the CTAGS source code, and this patch. Bascially the patch adds capabilities for the private, protected and public visibilty keywords.

# wget http://kent.dl.sourceforge.net/sourceforge\
/ctags/ctags-5.5.4.tar.gz
# tar -zxvf ctags-5.5.4.tar.gz
# wget http://svn.bitflux.ch/repos/public/misc/ctags-php5.patch
# mv ctags-php5.patch ctags-5.5.4
# cd ctags-5.5.4


Now patch the php.c file

# patch php.c ctags-php5.patch

Configure build and install CTAGS

# ./configure
# make
# make install


CTAGS is now installed, we can start to use it. I’d recommend creating tag file for different projects seperately, rather than one big one in your home folder or something. So move to your folder of choice and create the tags file.

# cd /path/to/your/project
# ctags -R


This may take a while depending on how many files you have. Once it is done, you’re ready to start using CTAGS with Vim. The ‘-t’ option for Vim opens the file containing that tag. So..

# vim -t 'MyClass'


… would open the MyClass.php class definition file. Once inside a file, hitting ctrl-] while the cursor is over a function/class name, Vim will attempt to open the file with that tag. Pressing ctrl-t will take you back a step.

Finding a tutorial, I sat down at my desktop machine and set about creating my first J2EE application. I’m a big fan of Gentoo Linux and try to use it’s portage package management as much as possible, making it easy to maintain my system, so rather than download JBoss like the tutorial says, I simply.

# emerge jboss

This went fine, as did firing up jboss and going to the console through my browser. Then I stumbled. Trying to invoke ’startDatabaseManager’ wouldn’t seem to work. It said it did, but the applet never appeared. An hour later, after customising the deploy XML file for HyperSonic, I was closer to having the database the way it needs to be, but still couldn’t get the applet to fire up. I googled for a while and found a handful of people having the same problems, but never for the same reason. In the end I gave up.

The thing is, right now I’m interested in the J2EE side of things, not so much the database, so it’s kind of annoying getting stuck so early. I’ll spend some time tonight trying to access the HSQLDB another way, if not I’ll try and adapt the tutorial to use MySQL!