Using Custom Properties In Phing

Phing allows you to set up certain parameters that can be used throughout the rest of the script. These might be used to define a non standard build directory, or to store database connection details that can be written to the connection file during the build.

Properties are defined using the property element, which you should place at the top of your build.xml file in order to make it easy for other developers to see what is going on. The following example defines a property and the uses the main target to print the property out.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
 <property name="property1" value="value1" />
 
 <target name="main">
  <echo>property1: ${property1}</echo>
 </target>
</project>

Running this build.xml file will product the following result.

C:\myProject>phing
Buildfile: C:\myProject\build.xml
 
myProject > main:
    [echo] property1: value1
 
BUILD FINISHED
 
Total time: 0.2119 seconds

It is possible to define properties using the command line. The following build.xml file is similar to the first but it tries to print out a second property that is not defined. The main target now has an attribute called if, which is used to see if a property is defined. If the property2 property is not defined then the target will not run, but it will also not produce any errors.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
 <property name="property1" value="value1" />
 
 <target name="main" if="property2">
  <echo>property1: ${property1}</echo>
  <echo>property2: ${property2}</echo>
 </target>
</project>

To run this script with property2 present use the -D flag along with phing.

phing -Dpropertyq2 value2

This can also be written as:

phing -Dpropertyq2=value2

The opposite of the if attribute is the unless attribute. If the property in the unless attribute is defined then the target element is not run. This provides a convenient way of turning on and off targets.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
 <property name="property1" value="value1" />
 
 <target name="main" unless="property2">
  <echo>property1: ${property1}</echo>
 </target>
</project>

The main target can be turned off in by using the following command.

phing -Dproperty2 value2

When a property is set on the command line it overrides any value that has been set for that property within the build.xml file.

You can also override properties from within the same build.xml file by using the override attribute of a second property element.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
 <property name="property1" value="value1" />
 
 <target name="main">
  <property name="property1" value="wibble" override="yes" />
  <echo>property1: ${property1}</echo>
 </target>
</project>

The value of the property1 property will now be 'wibble'.

Automated Build With Phing