Conditionally Setting Property Values with the Condition task

The previous example set up quite a complex assignment logic. More often, however, you’ll need a simple default value.  The condition task allows you to set a property’s value based upon configurable conditions. Here is an example:

<?xml version="1.0"?>
 
<!-- build xml -->
 
<project name="megaquiz"
         default="main">
 
    <condition property="dbpass" value="default">
        <not>
            <isset property="dbpass" />
        </not>
    </condition>
 
    <target name="main">
        <echo>pass:     ${dbpass}</echo>
    </target>
 
</project>

The condition task requires a property attribute. It also optionally accepts a value attribute, which is assigned to the property if the nested test clause resolves to true. If no value attribute is provided, then the property will be set to true if the nested test resolves to true.

The test clause is one of a number of tags, some of which like not in this example accept their own nested elements. I used the isset element which returns true if the referenced property is set. Because I want to assign a value to the dbpass property if it is not set, I need to negate this result by wrapping it in the not tag. This inverts the resolution of the tag it contains. So, in terms of PHP syntax, the condition task in my example is analogous to:

if ( ! isset( $dbname ) ) {
    $dbname = "default";
}

FileSet

Let’s say that you need to represent a directory in your build file, a common situation as you might imagine. You could use a property to represent this directory, certainly, but you’d run into problems straightaway if your developers use different platforms that support distinct directory separators. The answer is the FileSet data type. FileSet is platform independent, so if you represent a directory with forward slashes in the path, they will be automatically translated behind the scenes into backslashes when the build is run on a Windows machine. You can define a minimal fileset element like this:

<fileset dir="src/lib" />

As you can see, I use the dir attribute to set the directory I wish to represent. You can optionally add an id attribute, so that you can refer to the fileset later on:

<fileset dir="src/lib" id="srclib">

The FileSet data type is particularly useful in specifying types of documents to include or exclude. When installing a set of files, you may not wish those that match a certain pattern to be included. You can handle conditions like this in an excludes attribute:

<fileset dir="src/lib" id="srclib"
     excludes="**/*_test.php **/*Test.php" />

Notice the syntax I have used in the excludes attribute. Double asterisks represent any directory or subdirectory within src/lib. A single asterisk represents zero or more characters. So I am specifying that I would like to exclude files that end in _test.php or Test.php in all directories below the starting point defined in the dir attribute. The excludes attribute accepts multiple patterns separated by white space.

I can apply the same syntax to an includes attribute. Perhaps my src/lib directories contain many non-PHP files that are useful to developers but should not find their way into an installation. I could exclude those files, of course, but it might be simpler just to define the kinds of files I can include. In this case, if a file doesn’t end in .php, it isn’t going to be installed:

<fileset dir="src/lib" id="srclib"
     excludes="**/*_test.php **/*Test.php"
     includes="**/*.php" />

As you build up include and exclude rules, your fileset element is likely to become overly long. Luckily, you can pull out individual exclude rules and place each one in its own exclude subelement. You can do the same for include rules. I can now rewrite my FileSet like this:

<fileset dir="src/lib" id="srclib">
     <exclude name="**/*_test.php" />
     <exclude name="**/*Test.php" />
     <include name="**/*.php" />
</fileset>

You can see some of the attributes of the fileset element in Table 19-3.

PatternSet

As you build up patterns in your fileset elements (and in others), there is a danger that you will begin to repeat groups of exclude and include elements. In my previous example, I defined patterns for test files and regular code files. I may add to these over time (perhaps I wish to include .conf and .inc extensions to my definition of code files). If I define other fileset elements that also use these patterns, I will be forced to make any adjustments across all relevant fileset elements.

You can overcome this problem by grouping patterns into patternset elements. The patternset element groups include and exclude elements so that they can be referenced later from within other types. Here I extract the include and exclude elements from my fileset example and add them to patternset elements:

<patternset id="inc_code">
     <include name="**/*.php" />
     <include name="**/*.inc" />
     <include name="**/*.conf" />
</patternset>
 
<patternset id="exc_test">
     <exclude name="**/*_test.php" />
     <exclude name="**/*Test.php" />
</patternset>

I create two patternset elements, setting their id attributes to inc_code and exc_test respectively. inc_code contains the include elements for including code files, and exc_test contains the exclude files for excluding test files. I can now reference these patternset elements within a fileset:

<fileset dir="src/lib" id="srclib">
     <patternset refid="inc_code" />
     <patternset refid="exc_test" />
</fileset>

To reference an existing patternset, you must use another patternset element. The second element must set a single attribute: refid. The refid attribute should refer to the id of the patternset element you wish to use in the current context. In this way, I can reuse patternset elements:

<fileset dir="src/views" id="srcviews">
     <patternset refid="inc_code" />
</fileset>

Any changes I make to the inc_code patternset will automatically update any types that use it. As with FileSet, you can place exclude rules either in an excludes attribute or a set of exclude subelements. The same is true of include rules.

Some patternset element attributes are summarized in Table 19-4.

FilterChain

The types that I have encountered so far have provided mechanisms for selecting sets of files. FilterChain, by contrast, provides a flexible mechanism for transforming the contents of text files.

In common with all types, defining a filterchain element does not in itself cause any changes to take place. The element and its children must first be associated with a task—that is, an element that tells Phing to take a course of action. I will return to tasks a little later.

A filterchain element groups any number of filters together. Filters operate on files like a pipeline—the first alters its file and passes its results on to the second, which makes its own alterations, and so on. By combining multiple filters in a filterchain element, you can effect flexible transformations.

Here I dive straight in and create a filterchain that removes PHP comments from any text passed to it:

<filterchain>
    <stripphpcomments />
</filterchain>

The StripPhpComments task does just what the name suggests. If you have provided detailed API documentation in your source code, you may have made life easy for developers, but you have also added a lot of dead weight to your project. Because all the work that matters takes place within your source directories, there is no reason why you should not strip out comments on installation.

Let’s sneak a peek of the next section and place the filterchain element in a task:

<target name="main">
    <copy todir="build/lib">
        <fileset refid="srclib"/>
        <filterchain>
            <stripphpcomments />
        </filterchain>
    </copy>
</target>

The Copy task is probably the one you get most use out of. It copies files from place to place. As you can see, I define the destination directory in the todir attribute. The source of the files is defined by the fileset element I created in the previous section. Then comes the filterchain element. Any file copied by the Copy task will have this transformation applied to it.

Phing supports filters for many operations including stripping new lines (StripLineBreaks) and replacing tabs with spaces (TabToSpaces). There is even an XsltFilter for applying XSLT transformations to source files! Perhaps the most commonly used filter, however, is ReplaceTokens. This allows you to swap tokens in your source code for properties defined in your build file, pulled from environment variables, or passed in on the command line. This is very useful for customizing an installation. It’s a good idea to centralize your tokens into a central configuration file for easy overview of the variable aspects of your project.

ReplaceTokens optionally accepts two attributes, begintoken and endtoken. You can use these to define the characters that delineate token boundaries. If you omit these, Phing will assume the default character of @. In order to recognize and replace tokens, you must add token elements to the replacetokens element. Now to add a replacetokens element to my example:

<copy todir="build/lib">
        <fileset refid="srclib"/>
        <filterchain>
            <stripphpcomments />
            <replacetokens>
                 <token key="dbname" value="${dbname}" />
                 <token key="dbhost" value="${dbhost}" />
                 <token key="dbpass" value="${dbpass}" />
            </replacetokens>
        </filterchain>
</copy>

As you can see, token elements require key and value attributes. Let’s see the effect of running this task with its transformations on a file in my project. The original file lives in a source directory, src/lib/Config.php:

/**
 * Quick and dirty Conf class
**/
class Config {
    public $dbname ="@dbname@";
    public $dbpass ="@dbpass@";
    public $dbhost ="@dbhost@";
}

Running my main target containing the Copy task defined previously gives the following output:

$ phing

Buildfile: /home/bob/working/megaquiz/build.xml
 
megaquiz > main:
 
     [copy] Copying 8 files to /home/bob/working/megaquiz/build/lib
     [filter:ReplaceTokens] Replaced "@dbname@" with "megaquiz"
     [filter:ReplaceTokens] Replaced "@dbpass@" with "default"
     [filter:ReplaceTokens] Replaced "@dbhost@" with "localhost"
 
BUILD FINISHED
 
Total time: 0.1413 seconds

The original file is untouched, of course, but thanks to the Copy task, it has been reproduced at build/lib/Config.php:

class Config {
    public $dbname ="megaquiz";
    public $dbpass ="default";
    public $dbhost ="localhost";
}

Not only has the comment been removed, but the tokens have been replaced with their property equivalents.

Echo

The Echo task is perfect for the obligatory “Hello World” example. In the real world, you can use it to tell the user what you are about to do or what you have done. You can also sanity-check your build process by displaying the values of properties. As you have seen, any text placed within the opening and closing tags of an echo element will be printed to the browser:

<echo>The pass is '${dbpass}', shhh!</echo>

Alternatively, you can add the output message to a msg attribute:

<echo msg="The pass is '${dbpass}', shhh!" />

This will have the identical effect of printing the following to standard output:

[echo] The pass is 'default', shhh!

Copy

Copying is really what installation is all about. Typically, you will create one target that copies files from your source directories and assembles them in a temporary build directory. You will then have another target that copies the assembled (and transformed) files to their output locations. Breaking the installation into separate build and install phases is not absolutely necessary, but it does mean that you can check the results of the initial build before committing to overwriting production code. You can also change a property and install again to a different location without the need to run a potentially expensive copy/replace phase again.

At its simplest, the Copy task allows you to specify a source file and a destination directory or file:

<copy file="src/lib/Config.php" todir="build/conf" />

As you can see, I specify the source file using the file attribute. You may be familiar already with the todir attribute, which is used to specify the target directory. If the target directory does not exist, Phing will create it for you.

If you need to specify a target file, rather than a containing directory, you can use the tofile attribute instead of todir.

<copy file="src/lib/Config.php" tofile="build/conf/myConfig.php" />

Once again, the build/conf directory is created if necessary, but this time, Config.php is renamed to myConfig.php.

As you have seen, to copy more than one file at a time, you need to add a fileset element to copy:

<copy todir="build/lib">
    <fileset refid="srclib"/>
</copy>

The source files are defined by the srclib fileset element, so all you have to set in copy is the todir attribute.

Phing is smart enough to test whether or not your source file has been changed since the target file was created. If no change has been made, then Phing will not copy. This means that you can build many times and only the files that have changed in the meantime will be installed. This is fine, as long as other things are not likely to change. If a file is transformed according to the configuration of a replacetokens element, for example, you may want to ensure that the file is transformed every time that the Copy task is invoked. You can do this by setting an overwrite attribute:

<copy todir="build/lib" overwrite="yes">
    <fileset refid="srclib"/>
    <filterchain>
         <stripphpcomments />
         <replacetokens>
             <token key="dbpass" value="${dbpass}" />
         </replacetokens>
    </filterchain>
</copy>

Now whenever copy is run, the files matched by the fileset element are replaced whether or not the source has been recently updated.

You can see the copy element summarized in Table 19–5.

Input

You have seen that the echo element is used to send output to the user. To gather input from the user, I have used separate methods involving the command line and an environment variable. These mechanisms are neither very structured nor interactive, however.

The input element allows you to present the user with a prompt message. Phing then awaits  input which it assigns it to a property. Here’s an example:

<target name="setpass" unless="dbpass">
    <input message="You don't seem to have set a db password"
           propertyName="dbpass"
           defaultValue="default"
           promptChar=" >" />
</target>
 
<target name="main" depends="setpass">
    <echo>pass:     ${dbpass}</echo>
</target>

Once again, I have a default target: main. This depends on another target, setpass, which is responsible for ensuring that the dbpass property is populated. To this end, I use the target element’s unless attribute, which ensures that it will not run if dbpass is already set.

The setpass target consists of a single input task element. An input element can have a message attribute, which should contain a prompt for the user. The propertyName attribute is required and defines the property to be populated by user input. If the user presses Enter at the prompt without setting a value, the property is given a fallback value if the defaultValue attribute is set. Finally, you can customize the prompt character using the promptChar attribute—this provides a visual cue for the user to input data. Let’s run Phing using the previous targets:

$ phing

Buildfile: /home/bob/working/megaquiz/build.xml
 
megaquiz > setpass:
You don't seem to have set a db password [default] > mypass
megaquiz > main:
     [echo] pass:     mypass
 
BUILD FINISHED
 
Total time: 6.0322 seconds

The input element is summarized in Table 19-6.

Delete

Installation is generally about creating, copying, and transforming files. Deletion has its place as well, however. This is particularly the case when you wish to perform a clean install. As I have already discussed, files are generally only copied from source to destination for source files that have changed since the last build. By deleting a build directory, you ensure that the full compilation process will take place.

Here I delete a directory:

<target name="clean">
    <delete dir="build" />
</target>

When I run phing with the argument clean (the name of the target), my delete task element is invoked. Here’s Phing’s output:

$ phing clean

Buildfile: /home/bob/working/megaquiz/build.xml
 
megaquiz > clean:
   [delete] Deleting directory /home/bob/working/megaquiz/build
 
BUILD FINISHED

The delete element accepts an attribute, file, which can be used to point to a particular file. Alternatively, you can fine-tune your deletions by adding a fileset subelement to delete.