phpunit

There are a handful of PHP development tools that I find myself using project after project. One of them is Phing, a PHP-centered build tool similar to Ant, rake, or GNU Make.

The primary purpose of Phing is to make it easy for PHP developers to write build scripts for our applications. If you are familiar with Ruby on Rails, you might compare this to rake's usage. rake makes it easy to manage your Rails application. You can rebuild the database, start and stop the webserver, and so on from within rake.

Phing uses a declarative XML language to create targets (commands you can run) that are composed of tasks (individual steps for each command). Phing is built entirely in PHP, and is easily extended. Even without writing a line of PHP, you can squeeze a seemingly endless number of tasks out of a Phing script.

Here are some common tasks I use Phing for in my PHP projects. The first four meet some common needs. The last one is by far the coolest, though.

1. Let Phing catch your typos.
2. Automate Your Automated Testing.
3. Let Phing Write Your Documentation
4. Package Your Applications
5. Build Your Own Toolchain

I have recently converted some of my PHP projects over to use the awesome Phing build tool. Phing is similar to Apache Ant, a tool I am familiar with from my Java development days. I have crafted Phing's build.xml for QueryPath to handle building packages, generating API docs, running coverage analyses, linting, and (of course) running QueryPath's ~250 tests.

Having left IDEs behind for the time being, I have been working hard to build an personalized toolchain for PHP development. I've settled on TextMate as my editor (though I still use vim quite often). One thing I wanted to be able to do is run unit tests from within TextMate.

Initially I built a shell script to run the unit tests. But after moving to Phing, it seemed like it should be possible to take advantage of Phing's unit test running abilities (and lovely HTML output) from within TextMate. Working this out took two major stages:

1. Writing a custom target in Phing's build.xml
2. Creating a simple TextMate bundle for running Phing tasks

This article shows how to accomplish each of these steps.

While working on various PHPUnit tests, I was running some database queries. During the tear-down for my tests, I repeatedly received the following error:

General error: 6 database table is locked

The line of code generating this error (from my unit test's tearDown()) was this:

$db->exec('DROP TABLE qpdb_test');

Here, $db was a PDO object connected to a SQLite database. This line of code simply attempts to drop the table that the unit test has been working with.

Initially I could not find the root of the problem. A Google search just about convinced me that the problem was actually with the SQLite driver. However, I managed to temporarily work around the error by skipping the table drop and running a DELETE FROM qpdb_test instead. This worked as expected. After deleting, I discovered the problem.

One of my unit tests was failing. Because PHPUnit (correctly) traps all errors and catches all exceptions, the failed unit test did not stop the execution of the program. Instead, it began the tear-down procedure. However, the premature failure did prevent the PDOStatement's cursor from being closed. With the cursor left open, the DROP TABLE could not successfully be run. And when the DROP failed, the program prematurely exited (as this was in tear-down, not in a test).

A Google search turned up all sorts of theories about why the database tables were locked. (Apparently, others have had this same problem in the context of unit testing.) In the end, though, it was simply a matter of PDO performing as documented, PHPUnit performing as documented, and my code not performing as documented.