Using Phing, the PHP Build Tool

Key Takeaways

Phing is a PHP project build tool based on Apache Ant that helps automate tasks such as running unit tests, applying database changes, and deploying application code. This aids in preventing errors that can occur in manual processes, especially in continuous integration workflows.
Phing uses XML files to define tasks. These tasks can be grouped into targets, which can be invoked individually or depend on other targets. Tasks can range from simple actions like echoing a message to more complex actions like FTP deployment. Phing also allows the creation of custom tasks.
Phing is not limited to PHP-specific operations but can also handle framework-specific operations. This makes it a versatile tool for any PHP project. It also aids in automating the deployment process, handling errors, and generating documentation.

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:

directory structure

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

Frequently Asked Questions (FAQs) about Using Phing

What is the basic structure of a Phing build file?

A Phing build file is an XML file that defines the tasks to be executed. It starts with a tag that includes attributes like name, default, and basedir. The tag defines a series of tasks that can be executed together. Each task is represented by a specific XML tag like , , etc. The tasks are executed in the order they appear in the target.

How can I use Phing for continuous integration?

Phing can be used in continuous integration to automate the build and deployment process. You can define tasks for code linting, unit testing, generating documentation, packaging the code, and deploying it to the server. These tasks can be triggered automatically whenever there is a change in the code repository.

How can I extend Phing with custom tasks?

Phing allows you to create custom tasks by extending the Task class. You need to implement the main() method where you define the task’s behavior. Once the custom task class is created, you can use the tag in the build file to register the task.

What are the differences between Phing and other build tools like Ant or Maven?

Phing is specifically designed for PHP projects, while Ant and Maven are for Java. Phing uses XML for its build files like Ant, but it has built-in tasks for PHP-specific operations like running PHPUnit tests or generating PHPDocumentor documentation. Maven, on the other hand, uses a convention-over-configuration approach and has a more complex lifecycle.

How can I handle errors in Phing?

Phing provides several ways to handle errors. You can use the task to stop the build process if a certain condition is met. You can also use the task to catch exceptions and handle them appropriately. Additionally, you can configure the logging level to control the amount of information displayed when an error occurs.

Can I use Phing with Laravel or other PHP frameworks?

Yes, Phing can be used with any PHP project, including Laravel or other frameworks. You can define tasks to handle framework-specific operations like running migrations or seeding the database.

How can I run Phing tasks in parallel?

Phing doesn’t support running tasks in parallel out of the box. However, you can achieve this by using the task to run separate Phing processes in the background.

Can I use Phing to deploy my application?

Yes, Phing can be used to automate the deployment process. You can define tasks to package the application, upload it to the server, and perform any necessary setup tasks.

How can I use variables in Phing?

You can define variables using the tag and use them later in the build file. Variables can be set from a properties file, from the command line, or from the environment.

Can I use Phing to generate documentation for my project?

Yes, Phing has built-in tasks for generating documentation using tools like PHPDocumentor or ApiGen. You can configure the documentation generation process by specifying the source and destination directories, the output format, and other options.