Talk In Code

When a project gets complicated then so to can the build.xml file associated with it. You might find it necessary to have multiple different filesets, each of which do something different, but all of which have the same core files that they use. Multiple filesets are useful if you want to create a version of your project with all of the testing files in place so that it can be tested by external developers.

Creating multiple filesets can create problems, one of which is maintenance. Confusion can also occur even if you have a single large fileset where lots of different rules for including and excluding files are defined.

This is where the patternset element comes in. You can create a set of reusable file lists that can be used by more than one fileset, but which also makes maintenance a little easier.

The following snippet shows two patternset elements that show include files and exclude files.

<patternset id="inc_files">
 <include name="**/*.php" />
 <include name="something/**" />
</patternset>
 
<patternset id="exc_files">
 <exclude name="**/*_test.php" />
 <exclude name="myProject_build/**" />
</patternset>

This is then used by the fileset element in the following way.

<fileset dir="./" id="myProjectFiles">
 <patternset refid="inc_files" />
 <patternset refid="exc_files" />
</fileset>

Notice that the pattern set definition contains the id attribute, whereas the patternset within the fileset contains a refid attribute. The refid attribute must contain the name of a patternset, defined by using the id attribute.

You can also add in exclude and include elements into the fileset, along with any patternset elements.

<fileset dir="./" id="myProjectFiles">
 <patternset refid="inc_files" />
 <patternset refid="exc_files" />
 <include name="**/bla*.php" />
</fileset>

One of the main reasons to use Phing is to create a copy of your project in another directory that you can then use as your distribution copy. Your working directory might contain lots of testing code that is not needed in the final build.

To copy a file from one directory to another using Phing you need to use the copy element. Here is a simple example where a single file is copied from one directory to another.

<?xml version="1.0"?>
<!-- build xml -->
<project name="myProject" default="main">
<target name="main">
<copy file="index.php" tofile="myProject_build/index.php" />
</target>
</project>

This isn’t entirely useful as you will need to create a rule for every file you want transfered, which might be a few. To copy a directory you need to set up a fileset element. This will contain a list of files and directories that you want to be copied. A fileset element can contain include and exclude rules that govern which files will be used. Here is an example of a fileset, which would normally be on the root of the project element.

<fileset dir="./" id="myProjectFiles">
 <exclude name="**/*_test.php" />
 <include name="**/*.php" />
</fileset>

In this example we are excluding any file in this and any sub directory that has a filename ending in _test.php as these will be our test files that we don’t want copied. We then include any file that contains the .php extension. Because any exclude rules override any include rules this will work as expected and only copy across .php files without a _test at the end of the file name.

You can also specify a directory and everything in it by using the following include rule.

<include name="something/**" />

The previous fileset example can also be written as the following, although I don’t recommend this as it can get complicated!

<fileset dir="./" id="myProjectFiles" includes="**/*.php something/**" excludes="**/*_test.php" /&gtl

To do something useful with this fileset we can use the copy element again. The main difference here is that we are using the todir attribute of the copy element to designate the destination of the copy.

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

If you run this it will copy all the files (without the exceptions) and directories from the current directory to a directory called myProject_build. If the destination directory doesn’t exist then phing will create it. This works well, but if you run this code a second time it will copy the myProject_build into itself and you will get a recursive directory structure, which is quite messy and probably not what you want. There are two ways to prevent this. The first is to store your project in a subdirectory from your build.xml file and change your fileset rule accordingly. The second way is to add on an exclude rule to your fileset to specifically ignore the build directory and all of its contents.

<exclude name="myProject_build/**" />

Using the fileset and copy elements in this manner allows you to perform operations on the files as you copy them. This might be, for example, adding in a version number to the top of each file using a token replace.