Setting up continuous integration for PHP using Hudson and Phing

In this, my first post, I’m going to write about the benefits of Unit Testing and how Continuous Integration (CI) can be used to get the best out of Unit Testing. This will include details of how I setup a CI system using Hudson CI server, Phing build tool combined with various other analysis tools (including PHP Unit).

One of the best explanations of Unit Testing I’ve read was posted by benzado on Stack Overflow.

Unit testing is a lot like going to the gym. You know ...

it is good for you, all the arguments make sense, so you start working out. There’s an initial rush, which is great, but after a few days you start to wonder if it is worth the trouble.

The difficulty with Unit Testing is keeping it up. It is very easy to slip into poor habits and before you know it there’s a huge chunk of code with no tests. Possibly a huge, badly designed chunk of code, that didn’t benefit from having tests written before it was coded. Before you know what’s going on, you end up with a project that you really can’t write tests for, because retrofitting the tests is near impossible.

For me, there are two critical reasons for Unit Testing:

Enforcing good design

To be able to write tests, you need to be able to zero in on a “unit” of code, isolating it from all the rest of your 1,000,000 lines of web application. Writing Unit Tests forces you to design systems that have loose coupling because otherwise it is impossible to test.

Allowing changes to be made in confidence

Without Unit Tests, you get to the point where no one really wants to make any changes to the code. This is especially true in a commercial environment, where many people have worked on the code, including some key team member who has since left. Unit Tests allow you to make changes to one part of the code and be pretty convinced you haven’t messed up something else.

Continuous integration

Martin Fowler describes the process of Continuation Integration in detail. He suggests:

Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily – leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage.

The key idea behind CI is to do what is most painful often, namely “building” everyone’s code from source and making sure it all works.

A CI system usually consists of the following key elements:

Continuous integration

Developers commit code

CI server detects changes

CI server checksout code, runs tests, analyses code

CI server feeds back to development team

If you want to find out more about CI, I recommend the excellent book Continuous Integration: Improving Software Quality and Reducing Risk. There is an excerpt published on JavaWorld which covers a lot of the key advantages. In particular, it highlights:

1. Reduce risks

2. Reduce repetitive manual processes

3. Generate deployable software at any time and at any place

4. Enable better project visibility

5. Establish greater confidence in the software product from the development team

CI gets the most out of Unit Tests by forcing them to be run after every change. Not only that, but with a good CI setup, developers instantly know if they haven’t written enough tests. If avoids the situtation where Joe Bloggs has added in a huge chunk of code with zero tests.

Setting up CI for a PHP project

To get my environment setup, I consulted the following blog posts which are worth a read:

http://blog.jepamedia.org/2009/10/28/continuous-integration-for-php-with-hudson/

http://toptopic.wordpress.com/2009/02/26/php-and-hudson/

I’m assuming you’re using a CentOS 5 server (or I guess RHEL5). If not, you may still find various parts of this useful.

1. Install JDK

EPEL provide a set of CentOS packages, including a package for openJDK. This is the easiest way of installing Java.

Firstly, setup EPEL:

wget -O /etc/yum.repos.d/hudson.repo http://hudson-ci.org/redhat/hudson.repo

Next install OpenJDK:

yum install java-1.6.0-openjdk

2. Install Hudson

Download and install the CentOS RPM for Hudson:

wget -O /etc/yum.repos.d/hudson.repo http://hudson-ci.org/redhat/hudson.repo

rpm --import http://hudson-ci.org/redhat/hudson-ci.org.key

yum install hudson

Now Hudson is installed, we can start using the standard CentOS “service” command.

service hudson start

We can check Hudson is working by pointing the browser at port 8080 (the default Hudson port). Hudson will work “out of the box” and give you a web interface immediately. This is the primary reason I decided to go with Hudson over the other possibilities, eg: CruiseControl and phpUnderControl. Although I didn’t do an exhaustive analysis before I decided on Hudson, it just seemed right to me.

To get the graphing engine working for Hudson, you may need to install x.

yum groupinstall base-x

3. Install phing

Phing is a PHP project build system or build tool based on Apache Ant. A build tool ensures that the process of creating your working web application from source code happens in a structured and repeatable way. This helps reduce the possibility of errors caused by simply uploading files via FTP or some other simple method.

Make sure PEAR is installed for PHP (this is the easiest way of installing phing):

yum install php-pear

Then install the PEAR phing package:

pear channel-discover pear.phing.info

pear install phing/phing

4. Setup SVN

If you haven’t got a Subversion repository, you’re going to need one (or some other SCM tool like CVS, GIT or Mercurial).

yum install mod_dav_svn

The simplest setup involves creating a repo in /var/www/svn/<my repo>

mkdir -v /var/www/svn/test

svnadmin create --fs-type fsfs /var/www/svn/test

chown –R apache:apache /var/www/svn/test

Setup Apache by pretty much uncommenting the lines in /etc/httpd/conf.d/subversion.conf. Once Apache restarted, you’ll be able to get to it via /repos/test, assuming you’re using the default settings (sets up SVN on /repos). I haven’t gone into the details of getting SVN up and running; there are lots of resources out there that will help you do this.

5. Install PHP tools

PHPDocumentor – to generate documentation automatically from code

pear install PhpDocumentor

PHP CPD – “copy and paste detector” for PHP

This requires PHP 5.2. At time of writing, this wasn’t standard with CentOS 5, but is part of the CentOS “test” repo. This can be setup by creating a yum repo file, eg: /etc/yum.repos.d/centos-test.repo and populating with:

[c5-testing]

name=CentOS-5 Testing

baseurl=http://dev.centos.org/centos/5/testing/$basearch/

enabled=1

gpgcheck=1

gpgkey=http://dev.centos.org/centos/RPM-GPG-KEY-CentOS-testing

Then you can do:

yum update php

You may also need to upgrade pear; if the install of phpcpd fails (below). To do this, try:

pear upgrade pear

or, if this wants to be forced, and you think it’s a good idea (I did):

pear upgrade --force pear

Finally we can install phpcpd!

pear channel-discover pear.phpunit.de

pear install phpunit/phpcpd

PHP Depend – help analyse quality of codebase

Note you may have update PHP to include the DOM module (first line below).

yum install php-dom

pear channel-discover pear.pdepend.org

pear install pdepend/PHP_Depend-beta

PHP Code Sniffer – analyse code for adherence to style/standards

pear install PHP_CodeSniffer-1.2.0

PHP Unit – unit test framework for PHP

pear channel-discover pear.phpunit.de

pear install phpunit/PHPUnit

To make PHP Unit work, we need XDebug installed, the PHP profiler.

yum install php-devel gcc

pecl install xdebug

6. Install Hudson plugins

Use the web interface to install the following plugins (Manage Hudson -> Plugins).

Checkstyle

Clover

DRY

Green Balls (handy because it shows successful builds as green circles rather than blue)

JDepend

xUnit (will handle the output of PHPUnit test results XML)

7. Setup the phing build script

The Phing build script defines what steps will be taken to “build” the application.

Hudson itself works by placing our code into a project workspace. It will checkout the code from subversion and place it into the following location, where “Test” is the name of our project.

/var/lib/hudson/jobs/Test/workspace/

We can then use the Phing build script to carry out a number of processes on this code. When we talk about “building”, what we will actually do is place the code where we need it so it can actually run the website (we’ll keep this within the workspace) plus we run tests etc…

We’ll keep the build script in the subversion repository, so effectively it will be updated from SVN each build. For this approach to work, the following XML needs to be stored in a file named build.xml, stored in the project root folder (within trunk), eg: /trunk/build.xml

<?xml version="1.0" encoding="UTF-8"?>

<project name="test" basedir="." default="app">

<property name="builddir" value="${ws}/build" />

<target name="clean">

<echo msg="Clean..." />

<delete dir="${builddir}" />

</target>

<target name="prepare">

<echo msg="Prepare..." />

<mkdir dir="${builddir}" />

<mkdir dir="${builddir}/logs" />

<mkdir dir="${builddir}/logs/coverage" />

<mkdir dir="${builddir}/docs" />

<mkdir dir="${builddir}/app" />

</target>

<!-- Deploy app -->

<target name="app">

<echo msg="We do nothing yet!" />

</target>

<!-- PHP API Documentation -->

<target name="phpdoc">

<echo msg="PHP Documentor..." />

<phpdoc title="API Documentation"

destdir="${builddir}/docs"

sourcecode="yes"

defaultpackagename="MHTest"

output="HTML:Smarty:PHP">

<fileset dir="./app">

<include name="**/*.php" />

</fileset>

</phpdoc>

</target>

<!-- PHP copy/paste analysis -->

<target name="phpcpd">

<echo msg="PHP Copy/Paste..." />

<exec command="phpcpd --log-pmd=${builddir}/logs/pmd.xml source" escape="false" />

</target>

<!-- PHP dependency checker -->

<target name="pdepend">

<echo msg="PHP Depend..." />

<exec command="pdepend --jdepend-xml=${builddir}/logs/jdepend.xml ${ws}/source" escape="false" />

</target>

<!-- PHP CodeSniffer -->

<target name="phpcs">

<echo msg="PHP CodeSniffer..." />

<exec command="phpcs --standard=ZEND --report=checkstyle ${ws}/source > ${builddir}/logs/checkstyle.xml" escape="false" />

</target>

<!-- Unit Tests & coverage analysis -->

<target name="phpunit">

<echo msg="PHP Unit..." />

<exec command="phpunit --log-junit ${builddir}/logs/phpunit.xml --log-pmd ${builddir}/logs/phpunit.pmd.xml --coverage-clover ${builddir}/logs/coverage/clover.xml --coverage-html ${builddir}/logs/coverage/ ${ws}/source/tests"/>

</target>

</project>

8. Setup Hudson

The first step is to create a new job.

From the Hudson homepage, click New Job.

Enter a Job name, for example “Dave’s Product Build” and choose “Build a free-style software project”. Click OK.

Now you need to configure the job; the configuration form should be displayed immidiately after adding.

Under Source Code Management choose Subversion and enter:

Repository URL: http://www.myrepo.com/path/to/repo

Local module directory: source

Check “Use update” which speeds up checkout

Under Build Triggers select Poll SCM and enter the following schedule:

5 * * * *

10 * * * *

15 * * * *

20 * * * *

25 * * * *

30 * * * *

35 * * * *

40 * * * *

45 * * * *

50 * * * *

55 * * * *

Note that this will poll for changes to the repository every 5 minutes and rebuild if any changes are detected.

Under Build click the button to Add build step and choose Execute shell, enter the command:

phing -f $WORKSPACE/source/build.xml prepare app phpdoc phpcs phpunit -Dws=$WORKSPACE

Under Post-build Actions choose:

Check Publish Javadoc and then enter:

Javadoc directory = build/docs/

Check Publish testing tools result report and then click Add and pick PHP Unit, enter:

+ PHPUnit Pattern = build/logs/phpunit.xml

Check Publish Clover Coverage Report and enter:

+ Clover report directory = build/logs/coverage

+ Clover report file name = clover.xml

Check Publish duplicate code analysis results and enter:

+ Duplicate code results = build/logs/phpunit.pmd-cpd.xml

Check Publish Checkstyle analysis results and enter:

+ Checkstyle results = build/logs/checkstyle.xml

Finally, click Build Now to test it all works.

Hide