Using Phing, the PHP Build Tool

Phing is a PHP project build tool based on Apache Ant. A build system helps you to perform a group of actions using a single command. If you’re wondering why PHP needs a build tool, consider a work flow where you write code and unit tests on your local machine, and if the tests pass you upload the code to staging/production server and make any changes to the production database. Without a build file, you’ll need to go through each step manually. If you are doing continuous integration, you’ll be doing the same steps over and over again. It’s too easy to accidentally omit something in the process and end up with serious problem in production. Phing helps overcome such issues by automating tasks like running unit tests, applying database changes, deploying application code, etc. In this article I’ll show you some of the basics of working with Phing.

If you don’t have it already, you can install Phing using PEAR:

shameer@yukon:~$ sudo pear channel-discover pear.phing.info
shameer@yukon:~$ sudo pear install phing/phing

If you wish to use tasks like PHPUnit or PhpDocumentor then you’ll also need to install the dependent packages.

Phing Hello World

To show you how easy it is to create build files for Phing, let’s start with a “Hello World” build file. First create your project directory, and then inside it create a file named build.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<project name="HelloWorld" default="welcome" basedir="." description="a demo project">
 <property name="message" value="Hello World!"/>
 <target name="welcome">
  <echo msg="${message}"/>
 </target>
</project>

From the command line, navigate into the directory and run phing.

shameer@yukon:~/HelloWorld$ phing
Buildfile: /home/shameer/HelloWorld/build.xml

HelloWorld > welcome:

     [echo] Hello World!

BUILD FINISHED

Total time: 0.2275 seconds

The <project> element is the root element of the build file. The attribute default is required and specifies the default target to invoke if one isn’t supplied on the command line. Apart from that, you can also specify the project name, project base directory, and a description to help keep things organized.

The <target> element represents a named group of tasks that can be performed. For example, different targets might be defined to perform a backup or to update the database. A target can also be dependent upon another targets which must be performed before executing.

The <echo> element is a task, a single action that can be performed. There are number of core tasks in Phing which range from simple tasks like creating a directory to more complex tasks like performing XSLT transformations. You’re not limited to the tasks Phing provides, though; you can also create custom tasks.

The <property> element defines named values which can be used later throughout the build file. To reference the value of a property, specify it’s name between “${” and “}“. Keep in mind property names are case sensitive in Phing.

It’s not mandatory that you name your build file build.xml, but Phing will look for this name by default. If you use another name then you’ll need to specify the build file as an argument to the phing command, for example:

shameer@yukon:~/HelloWorld$ phing hello.xml

You can also invoke targets other than just the default by providing one or more target names in command line:

shameer@yukon:~/HelloWorld$ phing hello.xml target1

Multiple Targets

Let’s amend the build script and add additional targets. For the sake of example, I’ll assume the following directory structure is in place for the project:

Update build.xml so it now looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<project name="HelloWorld" default="welcome" basedir="." description="a demo project">
 <property name="message" value="Hello World!"/>
 <property name="buildDir" value="build"/>
 <property name="srcDir" value="src"/>
 <property name="ftp.host" value="ftp.example.com"/>
 <property name="ftp.port" value="21"/>
 <property name="ftp.username" value="user"/>
 <property name="ftp.password" value="password"/>
 <property name="ftp.dir" value="/public_html/"/>
 <property name="ftp.mode" value="ascii"/>

 <target name="welcome">
  <echo msg="${message}"/>
 </target>

 <target name="test">
  <phpunit printsummary="true" haltonfailure="true">
   <batchtest>
    <fileset dir="./tests">
     <include name="*Test.php"/>
    </fileset>
   </batchtest>
  </phpunit>
 </target>

 <fileset id="srcfiles">
  <include name="*"/>
  <exclude name="*.tmp"/>
 </fileset>

 <target name="build" depends="test">
  <echo msg="Copying to build directory..."/>
  <copy todir="${buildDir}">
  <fileset refid="srcfiles"/>
  </copy>
 </target>

 <ftpdeploy
  host="${ftp.host}"
  port="${ftp.port}"
  username="${ftp.username}"
  password="${ftp.password}"
  dir="${ftp.dir}"
  mode="${ftp.mode}">
  <fileset refid="srcfiles"/>
 </ftpdeploy>
</project>

Two targets have been added, test and build, and the default target has been changed to build. Now when you run Phing from the project directory it will call the build target and, since this target depends on the test target, Phing will run the test target first. The <phpunit> task invokes PHPUnit. Because the build process should not continue if any of the unit tests fail, its haltonfailure attribute has been set true. <batchtest> gets the files to be included from any number of nested <fileset> elements.

After the unit tests run successfully, the build target copies files specified in its <fileset> to the destination directory using <copy>. Notice that instead of giving the filenames here a refid is used. This references the <fileset> declared earlier with the ID srcfiles. It’s helpful to define a file set and reference it like this when you have complex regular expressions or need to refer to the same files in several places.

The <ftpdeploy> task connects to a remote server using FTP with the given credentials and transfers the files specified by the file set.

Summary

In this article I introduced you to the PHP build tool Phing. There is much more to Phing than what I discussed here, for example you can use it to help with database migrations. I recommend reading Phing’s excellent documentation to see all of what this powerful tool can do.

Image via Dino O / Shutterstock