Control Structures In Phing

Phing has a few different tasks and elements that allow you to select paths of code execution depending on what you need to happen in a build file. These are limited to loops and if statements, but a lot of functionality can be covered with just a couple of lines of XML.

Foreach Task

The foreach task iterates over a list of items, and/or fieldsets. For every item found in the loop a phing target will be called with the item in the list passed as a parameter to the target. The foreach target requires the following two attributes.

• target : This is the phing target to call on each parameter found in the param attribute.
• param : This is the parameter that will be passed to the target found in the target attribute.

The param attribute can contain either a property or a placeholder for a fileset. The property can be split in the same way as the explode() PHP function to split the string into an array. You can use the delimiter attribute to alter the separator, which defaults to a comma (,), but you must also include a list attribute to let the foreach target know what property to use.

Here is a simple example of a foreach task that loops through a series of numbers and prints them out in turn.

<?xml version="1.0"?>
<project name="foreachtest" default="foreachtest"> 

  <target name="foreachtest">
    <property name="list" value="1,2,3" />
    <foreach list="${list}" param="item" target="itemtarget" delimiter="," /> 
  </target>

  <target name="itemtarget">
    <echo>${item}</echo>
  </target>

</project>

This produces the following output.

foreachtest > foreachtest:

  [foreach] Calling Buildfile '/foreach.xml' with target 'itemtarget'

foreachtest > itemtarget:

     [echo] 1
  [foreach] Calling Buildfile '/foreach.xml' with target 'itemtarget'

foreachtest > itemtarget:

     [echo] 2
  [foreach] Calling Buildfile '/foreach.xml' with target 'itemtarget'

foreachtest > itemtarget:

     [echo] 3

BUILD FINISHED

Total time: 0.0632 seconds

The foreach target can also include a fileset or a mapper element as a nested argument. If this is the case then the parameter attribute will be used as a placeholder for the output of the nested elements. You can either create a new fileset within the foreach task, or just add a reference to one. The following Phing project creates a fileset and passes this to a foreach target, which prints each filename in turn. The directory I am using here is a common sounds directory found on most Debian/Ubuntu systems and so should produce some sort of result.

<?xml version="1.0"?>
<project name="foreachtest" default="foreachtest"> 

 <target name="foreachtest"> 
   <fileset dir="/usr/share/sounds/alsa/" id="thefiles">
     <include name="**" />
   </fileset>

   <foreach param="filename" target="foreachfile">
     <fileset refid="thefiles" />
   </foreach>
 </target>

 <target name="foreachfile">
   <echo>${filename}</echo>
 </target>
</project>

The idea here is that you would do more than just print out the name of the file. You could change the permissions of the file or perhaps something more involved. The benefits of using this approach mean that you have a target that does a single action on a file that can be used anywhere in your project, not just as the target of the foreach loop.

Conditions

Conditions are nested elements that are used in condition and if tasks to evaluate expressions and need to be understood before those elements can be used. Essentially, a conditional will evaluate something and return true or false. They can be split into comparators that compare two values and modifiers that change the output of a comparison in some way.

None of the comparators work on their own. Instead they are used in the condition and if tasks in order to drive those conditional statements. It is essential to understand these elements before looking at the condition and if elements.

Comparators

This consists of a series of comparison operators that compare one or more values and return a boolean result. The tables in this section were taken directly from the official Phing support documentation on conditions.

equals

This is the basic comparator and essentially compares two strings (provided by the arg1 and arg2 parameters) to one another. If the two strings are identical then the element returns true. The casesensitive parameter can be used to force the comparison to be case or non case sensitive. The trim parameter can also be used to trim whitespace from the arguments before they are compared. The two arguments can also accept properties as arguments. All of the following examples will return true.

<equals arg1="text" arg2="text" />
<equals arg1="TEXT" arg2="text" casesensitive="false" />
<equals arg1="TEXT" arg2=" text " trim="true" casesensitive="false" />

<property name="property1" value="TExt" />
<equals arg1="${property1}" arg2="text " trim="true" casesensitive="false" />

isset

The isset element returns true if a property has been set within the project scope. This is useful for checking to see if certain properties have been assigned before trying to use them. If the property hasn't been set then a property prompt or even a failure event can be used to act accordingly.

<property name="property1" value="text" />
<isset property="property1" />

contains

This element tests to see if one string contains another string. The string attribute is the string to search in and the substring attribute is the string to search for. If the string attribute contains substring then the condition will return true. The casesensitive attribute is a boolean value that can be used to turn on or off case sensitivity, the default being on. All of the following examples return true.

<contains string="some string" substring="me str" />
<contains string="SOME string" substring="me str" casesensitive="false" />
<contains string="abcdef" substring="a" />
<contains string="aBcDe" substring="aB" />
<contains string="aBcDe" substring="ab" casesensitive="false" />

istrue

This tests to see if a string evaluates to true. This uses standard PHP boolean string casting so any non-empty string will equate to true, whereas values like 'false', 0 or empty strings equate to false. All of the following examples will return true.

<istrue value="1" />
<istrue value="true" />
<istrue value="yes" />
<istrue value=" " />

isfalse

This is essentially the negative of istrue, but will return true if the value is false. All of the following examples will return true.

<isfalse value="0" />
<isfalse value="false" />
<isfalse value="" />

os

This tests to see if an operating system is of a given type. The element takes one attribute of family which can have one of three values. For Microsoft Windows based systems this is 'windows', for Apple Macintosh systems this is 'mac' and for Unix-like operating systems this is 'unix'. For example, if the family attribute is 'unix' and the script was being run on Ubuntu then this would return true. This is a pretty good way of running different functionality on different platforms and the options for each system are pretty simple.

<os family="unix" />

referenceexists

The referenceexists condition tests to see if a specified reference exists. A reference is a Phing type that references files, which includes filset, filelist, filterchains, chains, and file mappers.

The following will return true because the filset reference 'someid' exists.

<fileset id="someid">
  <include name="*.php" />
</fileset>

<referenceexists ref="someid" />

available

The available comparison is used to test to see if a file or directory exists. The file attribute details the file or directory name to be looked for. This can be swapped for the resource attribute to look for a specific path or the extension attribute to find a specific extension. The type attribute is used to differentiate between files and directories and the filepath attribute dictates which path should be used to look for the file.

This comparator works in the same way as the available task with the exception that the property and value attributes do nothing and will be ignored. It is a good way of double checking that things have worked correctly during the build. If the primary function of the build file is to create a compressed file then a check should be done to make sure the compressed file exists.

Using the following should always return true as this will find the build file.

<available extension="xml" />

The following will detect the /home directory on a Unix based system.

<available file="/home" type="dir" />

The following will return true if the the file index.php is within the directory /some/path.

<available file="index.php" type="file" filepath="/some/path/" />

Modifiers

Modifiers are used to modify the result of a comparison in some way. They do not compare things themsevles but they can be used to group together multiple comparisons or to negate a comparison. None of the comparison modifiers have any arguments.

not

This is the simplest form of modifier and will just negate the result of the comparison. This is a good way of testing to see if a property is set and acting accordingly using the isset comparison. The not comparison modifier cannot accept more than one condition, but it is possible to nest multiple comparisons within another comparison modifier and negate that. The following example will negate the result of the istrue comparison of false, which essentially returns true.

<not>
  <istrue value="false" />
</not>

The following is an example of nesting multiple comparisons into an and comparison modifier and then negating the result using the not modifier. In this case the result of the and comparison is false, but this negates and so the overall result is true.

<not>
  <and>
    <istrue value="false" />
    <istrue value="0" />
  </and>			
</not>

and

The and comparison modifier compares the result of multiple nested comparisons. The result is true if all of the inner comparisons are equal to true. The conditions will be evaluated in the order they appear in the build file. As soon as a condition is evaluated to false then no other conditions are evaluated in the rest of the and element. The following is an example of an and element comparing multiple nested comparison elements to return true.

<property name="property1" value="text" />

<and>
  <equals arg1="text" arg2="text" />
  <isset property="property1" />
  <contains string="some string" substring="me str" />
  <istrue value="1" />
  <isfalse value="0" />
</and>

or

This comparison modifier will evaluate multiple nested comparisons and return true if at least one of those conditions is true. The comparisons will be evaluated in the order they are found in the build file. When a true value is found the element will return true immediately and no other comparisons will be evaluated. The following example will evaluate the nested conditions and return true because at least one of them returns a true value.

<or>
  <equals arg1="text" arg2="TEXT" />
  <contains string="some string" substring="me str" />
</or>

Condition Task

The condition task is used to set a property if a condition is true. By default this property is set to be a boolean (i.e. the result of the comparison) but this can be changed by using the value attribute. The condition task must have exactly one nested comparison, although comparison modifiers (such as and) can be used when multiple comparisons need to be done. If the condition is not met then the property is not set. Here are a few examples of the condition task in action.

The following example sets the property 'textisthesame' to be true, based on the output of the equals comparison.

<condition property="textisthesame">
  <equals arg1="text" arg2="text" />
</condition>

The following example sets the property 'sametextandmac' to be true, based on the output of both the equals comparison and the build being run on a Mac computer.

<condition property="sametextandmac">
  <and>
    <equals arg1="text" arg2="text" />
    <os family="mac" />
  </and>
</condition>

The following example sets the property 'textisthesame' to be the string 'text' due to the value attribute being used in the condition task.

<condition property="textisthesame" value="text">
  <equals arg1="text" arg2="text" />
</condition>

The following example will not set the property because the result of the equals comparison is false. If you try to use this property elsewhere in the build file you will just print the name of the property.

<condition property="textisthesame">
  <equals arg1="text" arg2="notthesame" />
</condition>

If Task

http://www.phing.info/docs/guide/stable/chapters/appendixes/AppendixB-C…

The if task is a bit more complex than the condition task in that it is able to direct the flow of the execution of the build file. It works in much the same way that an if statement is used in normal programming, although it can be a little difficult to understand at first due to the nested XML syntax. The if task has no attributes and on it's own doesn't really do all that much, the real work is done by a comparison and the then, else, and elseif child elements. These child elements direct the flow of the build file depending on the outcome of the if comparison. The then and else child elements must be used only once within an if statement.

The elseif element acts like a sub if task and so must also have it's own comparison along with an then or elseif elements. The only exception here is that the elseif element must not contain an else element. It is also possible to nest if tasks to create complex comparisons. Here are a few examples of the if statement in action.

The following if task compares two properties and prints a message if they are the same.

<property name="text1" value="text" />
<property name="text2" value="text" />

<if>
  <equals arg1="${text1}" arg2="${text2}" />
  <then>
    <echo message="The two strings are the same." />
  </then>
</if>

The following is an example of using the and condition modifier in an if task. This just tests to see if two values are false and prints a message if they are.

<if>
  <and>
    <isfalse value="false" />
    <isfalse value="0" />
  </and>
  <then>
    <echo message="The two values are false." />
  </then>
</if>

The following if task will print a message depending on whether or not it is run on Windows.

<if>
 <os family="windows" />
 <then>
   <echo>You are running this build file on Windows.</echo>
 </then>
 <else>
   <echo>You are not running this build file on Windows</echo>
 </else>
</if>

The following if task will detect what operating system the build file is being run on and print a message. Notice that the elseif element here contains it's own comparison and then child element in order to compare and act on the comparison.

<if>
  <os family="windows" />
  <then>
    <echo message="This build file is being run on Windows.'" />
  </then>

  <elseif>
    <os family="mac" />
    <then>
      <echo message="This build file is being run on OSX.'" />
    </then>
  </elseif>

  <else>
    <echo message="This build file is being run on Linux.'" />
  </else>
</if>

The following if statement sets a property with a default value if the property doesn't exist. This is a good way of allowing properties to be passed to build files but to also have them available if the property isn't present.

<if>
  <not>
    <isset property="docs_path" />
  </not>
  <then>
    <resolvepath propertyName="docs_path" file="/some/static/path" />     
  </then>
</if>

The following is an example taken from a Drupal build file that puts the apc.php file into the correct place for it to be used by the system. It is an example of using an if statement with a then, elseif, and else element.

On some platforms the acp.php file is kept as a compressed 'gz' file that must be extracted. This file exists then the file is copied, to the destination directory before being extracted. The copied compressed file is then deleted as it is not needed. If the apc.php file is present then it is just copied into the correct place. Finally, the build file will announce if it is unable to find the file on the current system.

<if>
  <available file="/usr/share/doc/php-apc/apc.php.gz" />
  <then>
    <echo>Compressed apc file found, extracting.</echo>
    <mkdir dir="/docroot/sites/all/libraries/APC/" />
    <copy file="/usr/share/doc/php-apc/apc.php.gz" tofile="/docroot/sites/all/libraries/APC/apc.php.gz" overwrite="true" />
    <exec command="gunzip apc.php.gz" dir="/docroot/sites/all/libraries/APC/" />
    <copy todir="${make_path}/docroot/sites/all/libraries/APC/">
      <mapper type="glob" from="apc.php" to="apc.php.inc"/>
      <fileset dir="/docroot/sites/all/libraries/APC/">
        <include name="apc.php" />
      </fileset>
    </copy>
    <delete file="/docroot/sites/all/libraries/APC/apc.php" />
  </then>

  <elseif>
    <available file="/usr/share/doc/php-apc/apc.php" />
    <then>
      <echo>Uncompressed apc file found, copying</echo>
      <mkdir dir="/docroot/sites/all/libraries/APC/" />
      <copy file="/usr/share/doc/php-apc/apc.php" tofile="/docroot/sites/all/libraries/APC/apc.php.inc" overwrite="true" />
    </then>
  </elseif>

  <else>
    <echo>APC not installed on this system, skipping APC setup</echo>
  </else>
</if>

The following is a silly example that shows the syntax used when nesting if tasks but it useful to see how nesting works. This example will print 'True' because each if comparison will be true.

<if>
  <istrue value="true" />
  <then>
    <if>
      <istrue value="true" />
        <then>
          <if>
            <istrue value="true" />
            <then>
              <echo>True</echo>
            </then>
          </if>
        </then>
    </if>
  </then>
</if>