FilterChain Element In Phing

The FilterChain element is where the power of Phing really comes into its own. This element will allow you to change the contents of the files of a fileset. This can range from a simple stripping of comments, to replacing values and numerous other filters.

One of the simplest thing that can be done with filterset is to strip all comments from the files in question. Take the following PHP file with two comments.

<?php
/**
 *
 * This is a comment
 *
 *
 **/
echo 'Hello World!';
 
// another comment.

These comments can be stripped out of the file by using the stripphpcomments element. This is added to the copy element in the following way.

<?xml version="1.0"?>
<!-- build xml -->
 <project name="myProject" default="main">
 
 <fileset dir="./" id="myProjectFiles">
  <include name="**/*.php" />
  <exclude name="myProject_build/**" />
 </fileset>
 
 <target name="main">
  <copy todir="./myProject_build">
   <fileset refid="myProjectFiles" />
   <filterchain>
    <stripphpcomments />
   </filterchain>
   </copy>
 </target>
</project>

The PHP file now looks like this.

<?php
 
echo 'Hello World!';

Although this might be a nightmare to maintain it might be useful if reducing the size of your files is necessary. You might want to do this if you plan to sell your PHP software as it would make alteration by your customer a little bit more difficult.

Another use of the filterchain is to replace values within the code base. This is useful if you want to set a version number or a default database password. To replace a token with a value you need a property that can will store the value. You then need to go into your source code and replace any instance of the term you want to replace with the property name within @ symbols. Take the following PHP file.

<?php
/**
 *
 * This is a comment
 *
 *
 **/
$property1 = '@myProperty@';
echo 'Hello World!';
 
// another comment.

To replace the myProperty property with the value of "test", you need to use the replacetokens element, which can contain one or more token elements. The following build.xml file will replace all instances of the key myProperty with the value "test".

<?xml version="1.0"?>
<!-- build xml -->
 <project name="myProject" default="main">
 <property name="myProperty" value="test" />
 
 <fileset dir="./" id="myProjectFiles">
  <include name="**/*.php" />
  <exclude name="myProject_build/**" />
 </fileset>
 
 <target name="main">
  <copy todir="./myProject_build">
   <fileset refid="myProjectFiles" />
   <filterchain>
    <replacetokens>
      <token key="myProperty" value="${myProperty}" />
    </replacetokens>
   </filterchain>
   </copy>
 </target>
</project>

You will now see in your build output something like the following:

[filter:ReplaceTokens] Replaced "@myProperty@" with "test"

The token in each of the files will now be changed with the value of the property.

To see a list of the core filters available, take a look at the Phing filter appendix on the Phing website. You can even do something odd like only include the first 3 lines from each file, and append each line with the word "wibble".

<filterchain>
 <headfilter lines="3" />
 <prefixlines prefix="wibble: " />
</filterchain>

I can see why the headfilter might be useful in some instances where you want to test that your build file adds the correct file to each folder/zip file without including the whole thing. But where would you ever need to append a string to every line?

One final thing, if you change anything within your build file that replaces values then remember that phing will save time by not copying across any file that has already been copied and that hasn't changed. This means that if you change a filter and update you will see no changes unless you do one or both of the following:

• Manually delete any files in the target directories.
• Add an overwrite attribute to the copy element(s) in your target element(s). This will force phing to simply overwrite the files every time, even if they haven't changed.

Automated Build With Phing