Talk In Code

Aside from assigning and using your own properties Phing also comes with a set of built in properties that can be used to find out all sorts of information regarding the system that Phing is run on.

As an example, lets say you wanted to found out the operating system that phing is being run on. In this case you would use the variable host.os, which on a Windows XP system would print out WINNT.

There are a lot of different properties available, so I have included the table from the phing website at the bottom of this post as a reference. However, there is one special variable called env that needs further explanation. The env variable references any environment variables that have been set. For example, if you set an environment variable using the following shell command (on UNIX based systems only).

export TESTVAR=mytestvar

You can now reference this in your build.xml file by using the following.

${env.TESTVAR}

Here is a table of the built in properties available.

This list can also be found on the Phing website.

I have found that even though some of variables specifically say "not available on Windows" most of them will produce some sort of output, even on Windows machines. Here is a test build.xml file that you can use to see what the different variables print out on your system.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
 
 <target name="main">
  <echo>application.startdir ${application.startdir}</echo>
  <echo>host.arch ${host.arch}</echo>
  <echo>host.domain ${host.domain}</echo>
  <echo>host.fstype ${host.fstype}</echo>
  <echo>host.name ${host.name}</echo>
  <echo>host.os ${host.os}</echo>
  <echo>host.os.release ${host.os.release}</echo>
  <echo>host.os.version ${host.os.version}</echo>
  <echo>line.separator ${line.separator}</echo>
  <echo>os.name ${os.name}</echo>
  <echo>phing.file ${phing.file}</echo>
  <echo>phing.home ${phing.home}</echo>
  <echo>phing.version ${phing.version}</echo>
  <echo>phing.project.name ${phing.project.name}</echo>
  <echo>php.classpath${php.classpath}</echo>
  <echo>php.version ${php.version}</echo>
  <echo>project.basedir ${project.basedir}</echo>
  <echo>user.home ${user.home}</echo>
 </target>
</project>

This file misses out the env property as this is a custom property.

By default, Phing will look for a file in the current working directory called build.xml when you run it. This document tells Phing what it will be doing during the build. You can change this by using the -f or the -buildfile property of phing and giving the build file as the parameter. The following code makes phing look for a build file called wibble.xml.

phing -f wibble.xml

Assuming that the project is called myProject, then a minimal buildfile would be look like the following:

<?xml version="1.0"?>
<-- This is a comment -->
 
<project name="myProject" default="main">
  <target name="main" />
<project>

Of course, this doesn’t actually do anything at all, so it is utterly useless.

Every build file should consist of at a root project level, with one or more targets. Targets act as functions, they will copy your code to another directory, create a zip file, create documentation or do anything you want the build to do. You can run multiple targets, one after the other, by using the depends attribute. The following build file will run the first target before running the main target.

<?xml version="1.0"?>
<-- This is a comment -->
 
<project name="myProject" default="main">
  <target name="first" />
  <target name="main" depends="first" />
<project>

When run this will output the following:

C:\myProject>phing
Buildfile: C:\myProject\build.xml
 
myProject > first:
 
myProject > main:
 
BUILD FINISHED
 
Total time: 0.2197 seconds

You can call the targets whatever you want, but it is a good idea to call them by their functional name. You can also run single targets by running phing with an argument of the target in question. For example, if you want to run only the first target you would use the following command.

phing first

The target also supports the description attribute, which allows you to add a small description of that the target does. This is useful from a maintenance point of view, but also from a documentation point of view.

<?xml version="1.0"?>
<-- This is a comment -->
 
<project name="myProject" default="main">
  <target name="first" description="The first target." />
  <target name="main" description="The main and final target." depends="first" />
<project>

You can get phing to print out a list of the targets and their description by using the projecthelp flag like this.

phing -projecthelp

This will print out the following.

C:\myProject>phing -projecthelp
Buildfile: C:\myProject\build.xml
Default target:
-------------------------------------------------------------------------------
 main The main and final target
 
Main targets:
-------------------------------------------------------------------------------
 first The first target
 main The main and final target


To actually do anything in a target you need to add in other xml tags. As a quick example you can echo text to the screen by using the echo tag. The following build file will print out a message to the screen when run.

<?xml version="1.0"?>
<-- This is a comment -->
 
<project name="myProject" default="main">
 <target name="main">
  <echo>Have I built anything yet?</echo>
 </target>
<project>

To get Phing you will need to have PEAR installed along with PHP. On a Windows system you can install PEAR by running the go-pear.bat file and running through the prompts there.

To get Phing just run the following command.

pear install http://phing.info/pear/phing-current.tgz

You should see the install output looking like this:

downloading phing-current.tgz ...
Starting to download phing-current.tgz (361,527 bytes)
.........................................................................done: 361,527 bytes
install ok: channel://pear.php.net/phing-2.1.1

You can now run Phing by typing the following command:

phing

However, this will automatically try to find a file in the current directory called build.xml, and if it doesn’t find this file it will simply state the following:

Buildfile: build.xml does not exist!

Before stopping. This build.xml file (although it doesn’t have to be called this) is what controls what phing will do and is what you will spend most of your time looking at.

You can view which version of phing you are running by using the -v parameter.

phing -v

Which prints out something like:

Phing version 2.1.1

To view a list of available commands use the -h parameter.

phing -h

Which will print out:

phing [options] [target [target2 [target3] ...]]
Options:
-h -help print this message
-l -list list available targets in this project
-v -version print the version information and exit
-q -quiet be extra quiet
-verbose be extra verbose
-debug print debugging information
-logfile <file> use given file for log
-logger <classname> the class which is to perform logging
-f -buildfile <file> use given buildfile
-D<property>=<value> use value for given property
-find <file> search for buildfile towards the root of the
filesystem and use it
 
Report bugs to <dev@phing.tigris.org>