Appendix B: Core Tasks

This appendix contains a reference of all core tasks, i.e. all tasks that are needed to build a basic project. If you are looking for binarycloud related tasks, look in appendix ?.

This reference lists the tasks alphabetically by the name of the classes that implement the tasks. So if you are searching for the reference to the <copy> tag, for example, you will want to look at the reference of CopyTask .

AdhocTaskdefTask

The AdhocTaskdefTask allows you to define a task within your build file.

<target name="main"
description="==>test AdhocTask ">

<adhoc-task name="foo"><![CDATA[
class FooTest extends Task {
private $bar;

function setBar($bar) {
$this->bar = $bar;
}

function main() {
$this->log("In FooTest: " . $this->bar);
}
}
]]></adhoc-task>

<foo bar="B.L.I.N.G"/>
</target>

Note that you should use <![CDATA[ ... ]]> so that you don't have to quote entities within your <adhoc-task></adhoc-task> tags.

Parameters

Name Type Description Default Required
name String Name of XML tag that will represent this task. n/a Yes

AdhocTypedefTask

The AdhocTypedefTask allows you to define a datatype within your build file.

<target name="main"
description="==>test AdhocType">

<adhoc-type name="dsn"><![CDATA[
class CreoleDSN extends DataType {
private $url;

function setUrl($url) {
$this->url = $url;
}

function getUrl() { return $this->url; }
}
]]></adhoc-type>
<!-- creole-sql task doesn't exist; just an example --> <creole-sql file="test.sql"> <dsn url="mysql://root@localhost/test"/> </creole-sql>

</target>

Note that you should use <![CDATA[ ... ]]> so that you don't have to quote entities within your <adhoc-type></adhoc-type> tags.

Parameters

Name Type Description Default Required
name String Name of XML tag that will represent this datatype.. n/a Yes

AppendTask

The Append Task appends text or contents of files to a specified file.

<append destFile="${process.outputfile}">
  <filterchain>
    <xsltfilter style="${process.stylesheet}">
	     <param name="mode" expression="${process.xslt.mode}"/>
    </xsltfilter>
  </filterchain>
  <filelist dir="book/" listfile="book/PhingGuide.book"/>
</append>

In the example above, AppendTask is reading a filename from book/PhingGuide.book, processing the file contents with XSLT, and then appending the result to the file located at ${process.outputfile}. This is a real example from the build file used to generate this book!

Parameters

Name Type Description Default Required
destFile File Path of file to which text should be appended. n/a Yes
file File Path to file that should be appended to destFile. n/a No
text String Some literal text to append to file. n/a No

Supported Nested Tags

AvailableTask

Available Task tests if a resource/file is set and sets a certain property to a certain value if it exists.

<available file="/tmp/test.txt" property="test_txt_exists" value="Yes"/>

<available file="/home/foo" type="dir" property="properties.yetanother" />

<available file="/home/foo/bar" property="foo.bar" value="Well, yes" />

Here, AvailableTask first checks for the existance of either file or directory named test.txt in /tmp. Then, it checks for the directory foo in /home and then for the file or directory bar in /home/foo. If /tmp/test.txt is found, the property test_txt_exists is set to "Yes", if /home/foo is found and a directory, properties.yetanother is set to "true" (default). If /home/foo/bar exists, AvailableTask will set foo.bar to "Well, yes".

NB: the Available task can also be used as a condition.

Parameters

Name Type Description Default Required
property string Name of the property that is to be set. n/a Yes
value String The value the property is to be set to. "true" No
file String File/directory to check existence. n/a Yes (or resource)
resource String Path of the resource to look for. n/a Yes (or file)
type String (file|dir) Determines if AvailableTask should look for a file or a directory at the position set by file. If empty, it checks for either file or directory. n/a No
filepath String The path to use when looking up file. n/a No
followSymlinks Boolean Whether to dereference symbolic links when looking up file. false No

ChmodTask

Sets the mode of a file or directory.

Example

<chmod file="test.txt" mode="0755" />
<chmod file="/home/test" mode="0775" />
<chmod file="/home/test/mine.txt" mode="0500" verbose="true" />

For more informations, see chmod in the PHP Manual.

Attributes

Name Type Description Default Required
file String The name of the file or directory. You either have to specify this attribute, or use a fileset. n/a Yes
mode String The new mode (octal) for the file. Specified in octal, even if the first digit is not a '0'. n/a Yes
quiet Boolean Set quiet mode, which suppresses warnings if chmod() fails false No
failonerror Boolean This flag means 'note errors to the output, but keep going' true No
verbose Boolean Give more information in error message in case of a failure true No

Supported Nested Tags

ChownTask

Changes the owner of a file or directory.

Example

<chown file="my-file.txt" user="foo" />
<chown file="my-file.txt" user="username.groupname" />
<chown file="/home/test/my-directory" user="bar" />
<chown file="/home/test/my-file.txt" user="foo" verbose="true" failonerror="false" />

Attributes

Name Type Description Default Required
file String The name of the file or directory. You either have to specify this attribute, or use a fileset. n/a Yes
user String The new owner of the file. Can contain a username and a groupname, separated by a dot. n/a No
group String The new group owner of the file. n/a No
quiet Boolean Set quiet mode, which suppresses warnings if chmod() fails false No
failonerror Boolean This flag means 'note errors to the output, but keep going' true No
verbose Boolean Give more information in in error message in case of a failure true No

Supported Nested Tags

ConditionTask

Sets a property if a certain condition holds true - this is a generalization of Available and UpToDate.

If the condition holds true, the property value is set to true by default; otherwise, the property is not set. You can set the value to something other than the default by specifying the value attribute.

Conditions are specified as nested elements, you must specify exactly one condition - see the documentation for a complete list of nested elements.

Example

<condition property="isMacOrWindows">
    <or>
      <os family="mac"/>
      <os family="windows"/>
    </or>
  </condition>

Attributes

Name Type Description Default Required
property String The name of the property to set. n/a Yes
value String The value to set the property to. Defaults to "true". true No

Supported Nested Tags

CopyTask

Copies files or directories. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist. It is possible to explictly overwrite existing files.

Example

On the one hand, CopyTask can be used to copy file by file:

<copy file="somefile.txt" tofile="/tmp/anotherfile.bak" overwrite="true"/>

Additionally, CopyTask supports Filesets, i.e. you can easily include/exclude one or more files. For more information, see Appendix D -- pay particular attention to the defaultexcludes attribute. Mappers and Filters are also supported by CopyTask, so you can do almost everything that needs processing the content of the files or the filename.

<copy todir="/tmp/backup" >
  <fileset dir=".">
    <include name="**/*.txt" />
    <include name="**/*.doc" />
    <include name="**/*.swx" />
  </fileset>
  <filelist dir="." files="test.html"/>
</copy>
<copy todir="build" >
  <fileset defaultexcludes="false" expandsymboliclinks="true" dir=".">
    <include name="**/*.php" />
  </fileset>
</copy>

Notice: CopyTask does not allow self copying, i.e. copying a file to the same name for security reasons.

Symbolic links

By default, CopyTask does not expand / dereference symbolic links, and will simply copy the link itself. To enable dereferencing, set expandsymboliclinks to true in the <fileset> tag.

Attributes

Name Type Description Default Required
file String The source file. Yes
tofile String

The destination the file is to be written to. tofile specifies a full filename. If you only want to specify a directory to copy to, use todir.

Either this or the todir attribute is required.

n/a Yes (or todir)
todir String The directory the file is to be copied to. The file will have the same name of the source file. If you want to specify a different name, use tofile. The directory must exist. n/a Yes (or tofile)
overwrite Boolean Overwrite existing files even if the destination files are newer. false No
tstamp
or
preservelastmodified
Boolean If set to true, the new file will have the same mtime as the old one. false No
includeemptydirs Boolean If set to true, also empty directories are copied. true No
mode Integer Mode (octal) to create directories with. From umask No
haltonerror Boolean If set to true, halts the build when errors are encountered. true No

Supported Nested Tags

CvsTask

Allows rudimentary interfacing with the CVS versioning system.

As you would expect, this lets you do pretty much anything with CVS. The CvsTask calls ExecTask which actually does the command execution.

Example

<cvs cvsRoot=":pserver:guest@cvs.tigris.org:/cvs"
       module="phing" dest="${ws.dir}"/>

or, using the optional command line arguments:

<cvs output="patch" command="-q diff -u -N" />

Attributes

Name Type Description Default Required
cvsRoot String The root directory on the CVS server n/a No
CvsRsh String Path to the rsh to execute n/a No
port Integer Port ion the server to use 0 No
passfile String
filename
Name of file with CVS passwords n/a No
dest String The directory where checked out files should be placed n/a Yes
modules String The package/module to operate upon n/a Yes
tag String The tag of the package/module to operate upon n/a No
date String Use the most recent revision no later than the given date n/a No
quiet Boolean Quiet run false No
noexec Boolean If true, only report changes don't actually do anything false No
failonerror Boolean Stop the build process if the command returns any errors false No
compression Boolean If true, turns on compression using default (3) compression level false No
compressionlevel Integer Specifies compression level 1-9 false No
output String
filename
File to which output should be written n/a No
error String
filename
File to which error output should be written n/a No
command String Optional command line to be given to the CVS task null No

CvsPassTask

This lets you create your own cvs password file -- i.e. this is necessary if you want to provide a password in your build file.

If no password file is specified the default location .cvspass in users home directory is used.

Example

<!-- create a password file -->
<cvspass cvsRoot=":pserver:guest@cvs.tigris.org:/cvs" passfile="cvspass" password="guest"/>

<!-- use the just-created password file -->
<cvs cvsRoot=":pserver:guest@cvs.tigris.org:/cvs" module="phing" passFile="cvspass" />

Attributes

Name Type Description Default Required
cvsRoot String The root directory on the CVS server n/a Yes
passFile String Password file to add password to n/a No
password String Password to add to file n/a Yes

DeleteTask

Deletes a file or directory, or set of files defined by a fileset. See Appendix D for information on Filesets.

Example

<-- Delete a specific file -->
<delete file="/tmp/foo.bar" />

<-- Delete a directory -->
<delete dir="/tmp/darl" includeemptydirs="true" verbose="true" failonerror="true" />

<-- Delete using a fileset -->
<delete>
  <fileset dir="/tmp">
    <include name="*.bar" />
  </fileset>
</delete>

Attributes

Name Type Description Default Required
file String The file that is to be deleted. You either have to specify this attribute, dir, or use a fileset. n/a Yes (or dir)
dir String The directory that is to be deleted. You either have to specify this attribute, file, or use a fileset. n/a Yes (or file)
verbose Boolean Used to force listing of all names of deleted files. n/a No
quiet Boolean

If the file does not exist, do not display a diagnostic message or modify the exit status to reflect an error. This means that if a file or directory cannot be deleted, then no error is reported.

This setting emulates the -f option to the Unix rm command. Default is false meaning things are verbose

n/a No
failonerror Boolean If this attribute is set to true, DeleteTask will verbose on errors but the build process will not be stopped. false No
includeemptydirs Boolean Determines if empty directories are also to be deleted. false No

Supported Nested Tags

EchoTask

Echoes a message to the current loggers and listeners which means standard out unless overridden. A level can be specified, which controls at what logging level the message is filtered at.

The task can also echo to a file, in which case the option to append rather than overwrite the file is available, and the level option is ignored

Additionally, the task can echo the contents of a nested fileset element.

Examples

<echo msg="Phing rocks!" />

<echo message="Binarycloud, too." />

<echo>And don't forget Propel.</echo>

<echo file="test.txt" append="false">This is a test message</echo>

Attributes

Name Type Description Default Required
msg String The string that is to be send to the output. n/a Yes
message String Alias for msg. n/a Yes
file String The file to write the message to. n/a No
append Boolean Append to an existing file? false No
level String Control the level at which this message is reported. One of error, warning, info, verbose, debug. info No

Supported Nested Tags

ExecTask

Executes a shell command. You can use this to quickly add a new command to Phing. However, if you want to use this regularly, you should think about writing a Task for it.

Example

<-- List the contents of "/home". -->
<exec command="ls -l" dir="/home" />

<-- Start the make process in "/usr/src/php-4.0". -->
<exec command="make" dir="/usr/src/php-4.0" />

<-- List the contents of "/tmp" out to a file. -->
<exec command="ls -l /tmp > foo.out" escape="false" />

Attributes

Name Type Description Default Required
command String The command that is to be executed. n/a One of the two
executable String The command to execute without any command line arguments. n/a
dir String The directory the command is to be executed in. n/a No
output String Where to direct stdout. n/a No
error String Where to direct stderr. n/a No
os String Only execute if the os.name property contains specified text. n/a No
escape Boolean By default, we escape shell metacharacters before executing. Setting this to false will disable this precaution. TRUE No
passthru Boolean Whether to use PHP's passthru() function instead of exec(). FALSE No
logoutput Boolean Whether to log returned output as MSG_INFO instead of MSG_VERBOSE. FALSE No
spawn Boolean Whether to spawn unix programs to the background, redirecting stdout. FALSE No
returnProperty String Property name to set return value to from exec() call. n/a No
outputProperty String Property name to set output value to from exec() call. n/a No
checkreturn Boolean Whether to check the return code of the program, throws a BuildException when returncode != 0. FALSE No
level String Control the level at which status messages are reported. One of error, warning, info, verbose, debug. verbose No

Supported Nested Tags

FailTask

Causes the current build script execution to fail (throwing a BuildException) and the script to exit with an (optional) error message.

Example

<-- Exit with message -->
<fail message="Failed for some reason!" />

<--  Exit if ${errorprop} is defined -->
<fail if="errorprop" message="Detected error!" />

<-- Exit unless ${dontfail} prop is defined. -->
<fail unless="dontfail" message="Detected error!" />

Attributes

Name Type Description Default Required
message String The message to display (reason for script abort). n/a No
msg String Alias for message n/a No
if String Name of property that must be set for script to exit. n/a No
unless String Name of property that must not be set in order for script to exit. n/a No

ForeachTask

The foreach task iterates over a list, a list of filesets, or both. If both, list and filesets, are specified, the list will be evaluated first. Nested filesets are evaluated in the order they appear in the task.

Example

<!-- loop through languages, and call buildlang task with setted param -->
<property name="languages" value="en,fr,de" />
<foreach list="${languages}" param="lang" target="buildlang" />

<!-- loop through files, and call subtask task with set param and absparam -->
<foreach param="filename" absparam="absfilename" target="subtask">
  <fileset dir=".">
    <include name="*.php"/>
  </fileset>
</foreach>

Attributes

Name Type Description Default Required
list String The list of values to process, with the delimiter character, indicated by the "delimiter" attribute, separating each value. n/a No
target String The target to call for each token, passing the token as the parameter with the name indicated by the "param" attribute. n/a Yes
param String The name of the parameter to pass the tokens in as to the target. n/a Yes
absparam String The name of the absolute pathparameter to pass the tokens in as to the target (used while processing nested filesets). n/a No
delimiter String The delimiter string that separates the values in the "list" parameter. The default is ",". , No

Supported Nested Tags

IfTask

Perform some tasks based on whether a given condition holds true or not.

Attributes

This task doesn't have any attributes, the condition to test is specified by a nested element - see the documentation for a complete list of nested elements.

Just like the <condition> task, only a single condition can be specified - you combine them using <and> or <or> conditions.

In addition to the condition, you can specify three different child elements, <elseif> , <then> and <else> . All three subelements are optional. Both <then> and <else> must not be used more than once inside the if task. Both are containers for Phing tasks.

The <elseif> behaves exactly like an <if> except that it cannot contain the <else> element inside of it. You may specify as may of these as you like, and the order they are specified is the order they are evaluated in. If the condition on the <if> is false, then the first <elseif> who's conditional evaluates to true will be executed. The <else> will be executed only if the <if> and all <elseif> conditions are false.

Example

<if>
 <equals arg1="${foo}" arg2="bar" />
 <then>
   <echo message="The value of property foo is bar" />
 </then>
 <else>
   <echo message="The value of property foo is not bar" />
 </else>
</if>
<if>
 <equals arg1="${foo}" arg2="bar" />
 <then>
   <echo message="The value of property foo is 'bar'" />
 </then>

 <elseif>
  <equals arg1="${foo}" arg2="foo" />
  <then>
   <echo message="The value of property foo is 'foo'" />
  </then>
 </elseif>

 <else>
   <echo message="The value of property foo is not 'foo' or 'bar'" />
 </else>
</if>

ImportTask

Imports another build file into the current project.

On execution it will read another Phing file into the same Project. Functionally it is nearly the same as copy and pasting the imported file onto the end of the importing file.

Target Overriding

If a target in the main file is also present in at least one of the imported files, the one from the main file takes precedence.

So if I import for example a docs/build.xml file named builddocs, that contains a "docs" target, I can redefine it in my main buildfile and that is the one that will be called. This makes it easy to keep the same target name, so that the overriding target is still called by any other targets--in either the main or imported buildfile(s)--for which it is a dependency, with a different implementation. The target from docs/build.xml is made available by the name "builddocs.docs". This enables the new implementation to call the old target, thus enhancing it with tasks called before or after it.

Special Properties

Imported files are treated as they are present in the main buildfile. This makes it easy to understand, but it makes it impossible for them to reference files and resources relative to their path. Because of this, for every imported file, Phing adds a property that contains the path to the imported buildfile. With this path, the imported buildfile can keep resources and be able to reference them relative to its position.

So if I import for example a docs/build.xml file named builddocs, I can get its path as phing.file.builddocs, similarly to the phing.file property of the main buildfile. Additionally, the directory will be stored in phing.dir.builddocs.

Note that "builddocs" is not the filename, but the name attribute present in the imported project tag.

If import file does not have a name attribute, the phing.file.projectname and phing.dir.projectname properties will not be set.

Resolving Files Against the Imported File

Suppose your main build file called importing.xml imports a build file imported.xml , located anywhere on the file system, and imported.xml reads a set of properties from imported.properties :

<!-- importing.xml -->
<project name="importing" basedir="." default="...">
  <import file="${path_to_imported}/imported.xml"/>
</project>

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <property file="imported.properties"/>
</project>

This snippet however will resolve imported.properties against the basedir of importing.xml , because the basedir of imported.xml is ignored by Phing. The right way to use imported.properties is:

<!-- imported.xml -->
<project name="imported" basedir="." default="...">
  <property file="${phing.dir.imported}/imported.properties"/>
</project>

As explained above ${phing.file.imported} stores the full path of the build script, that defines the project called imported, (in short it stores the path to imported.xml) and ${phing.dir.imported} stores its directory. This technique also allows imported.xml to be used as a standalone file (without being imported in other project).

Example

<import file="path/to/build.xml"/>
<import file="path/to/build.xml" optional="true"/>

Attributes

Name Type Description Default Required
file String The file to import. n/a Yes
optional Boolean If true, do not stop the build if the file does not exist. false No

IncludePathTask

Sets the PHP include_path configuration option for the duration of this phing run.

Example 1 - Trivial use

<includepath classpath="new/path/here" />
<includepath classpath="path1:path2" />

Example 2 - Referencing a previously defined path

<path id="project.class.path">
  <pathelement dir="lib/"/>
  <pathelement dir="ext/"/>
</path>

<includepath classpathref="project.class.path" />

Attributes

Name Type Description Default Required
classpath String the new include path[s] n/a Yes
classPathRef String Reference to a previously defined Path type n/a No

InputTask

The InputTask can be used to interactively set property values based on input from the console (or other Reader).

Example

<!-- Getting string input -->
<echo>HTML pages installing to: ${documentRoot}</echo>
<echo>PHP classes installing to: ${servletDirectory}</echo>

<input propertyname="documentRoot">Web application document root</input>
<input propertyname="servletDirectory"
  defaultValue="/usr/servlets" promptChar="?">PHP classes install dir</input>

<echo>HTML pages installed to ${documentRoot}</echo>
<echo>PHP classes installed to ${servletDirectory}</echo>

<!-- Having the user choose from a set of valid choices -->
<echo>Choose a valid option:</echo>

<input propertyname="optionsChoice" validargs="foo,bar,bob">
  Which item would you like to use
</input>

Attributes

Name Type Description Default Required
propertyName String The name of the property to set. n/a No
defaultValue String The default value to be set if no new value is provided. n/a Yes
message String Prompt text (same as CDATA). n/a Yes
promptChar String The prompt character to follow prompt text. n/a No
validArgs String Comma-separated list of valid choices the user must supply. If used, one of these options must be chosen. n/a No

LoadFileTask

The LoadFileTask loads the contents of a (text) file into a single property.

Example

<loadfile property="version" file="version.txt"/>

Attributes

Name Type Description Default Required
property String The name of the property to set. n/a Yes
file (or srcFile) String The file to load. n/a Yes

Supported Nested Tags:

MkdirTask

Creates a directory, including any necessary but non-existent parent directories. Does nothing if the directory already exists.

Example

<-- Create a temp directory -->
<mkdir dir="/tmp/foo" />

<-- Using mkdir with a property -->
<mkdir dir="${dirs.install}/tmp" />

Attributes

Name Type Description Default Required
dir String The directory that is to be created. n/a Yes
mode Integer The mode to create the directory with. From umask No

MoveTask

Moves a file or directory to a new file or directory. By default, the destination file is overwritten if it already exists. When overwrite is turned off, then files are only moved if the source file is newer than the destination file, or when the destination file does not exist.

Source files and directories are only deleted if the file or directory has been copied to the destination successfully.

Example

<-- The following will move the file "somefile.txt" to "/tmp" and
    change its filename to "anotherfile.bak". It will overwrite
    an existing file. -->
<move file="somefile.txt" tofile="/tmp/anotherfile.bak" overwrite="true"/>

<-- This will move the "/tmp" directory to "/home/default/tmp",
    preserving the directory name. So the final name is
    "/home/default/tmp/tmp". Empty directories are also copied -->
<move file="/tmp" todir="/home/default/tmp" includeemptydirs="true" />

Attributes and Nested Elements

For further documentation, see CopyTask, since MoveTask only is a child of CopyTask and inherits all attributes.

PhingTask

This task calls another build file. You may specify the target that is to be called within the build file. Additionally, the <phing> Tag may contain <property> Tags (see PropertyTask).

Example

<-- Call target "xslttest" from buildfile "alternativebuildfile.xml" -->
 <phing phingfile="alternativebuild.xml" inheritRefs="true" target="xslttest" />

<-- Do a more complex call -->
<phing phingfile="somebuild.xml" target="sometarget">
  <property name="foo" value="bar" />
  <property name="anotherone" value="32" />
</phing>

Attributes

Name Type Description Default Required
inheritAll Boolean If true, pass all properties to the new phing project. true No
inheritRefs Boolean If true, pass all references to the new phing project. false No
dir String The directory to use as a base directory for the new phing project. Default is the current project's basedir, unless inheritall has been set to false, in which case it doesn't have a default value. This will override the basedir setting of the called project. n/a No
phingFile String The build file to use. Defaults to "build.xml". This file is expected to be a filename relative to the dir attribute given. n/a Yes
target String The target of the new Phing project to execute. Default is the new project's default target. n/a No
haltonfailure Boolean If true, fail the build process when the called build fails false No

Supported Nested Tags

Base directory of the new project

The base directory of the new project is set dependant on the dir and the inheritAll attribute. This is important to keep in mind or else you might run into bugs in your build.xml's. The following table shows when which value is used:

dir attribute inheritAll attribute new project's basedir
value provided true value of dir attribute
value provided false value of dir attribute
omitted true basedir of calling task (the build file containing the <phing> call.
omitted false basedir attribute of the <project> element of the new project

PhingCallTask

The PhingCallTask calls a target within the same Phing project.

A <phingcall> tag may contain <property> tags that define new properties. These properties are only set if properties of the same name have not been set outside the "phingcall" tag.

Important note about scope: every <phingcall> tag creates a new local scope. Thus, any properties or other variables set inside that scope will cease to exist (or revert to their previous value) once the <phingcall> tag completes.

Example

<target name="foo">
    <phingcall target="bar">
        <property name="property1" value="aaaaa" />
        <property name="foo" value="baz" />
    </phingcall>
</target>

In the example above, the properties property1 and foo are defined and only accessible inside the called target.

<target name="bar" depends="init">
    <echo message="prop is ${property1} ${foo}" />
</target>

Parameters

Name Type/Values Description Default Required
target string The name of the target in the same project that is to be called. n/a Yes

Supported Nested Tags

PhpEvalTask

With the PhpEvalTask, you can set a property to the results of evaluating a PHP expression or the result returned by a function/method call.

Examples

<php function="crypt" returnProperty="enc_passwd">
  <param value="${auth.root_passwd}"/>
</php>
<php expression="3 + 4" returnProperty="sum"/>
<php expression="echo 'test';">

Attributes

Name Type Description Default Required
function String The name of the Property. n/a One of these is required.
expression String The expression to evaluate. n/a
class String The static class which contains function. n/a No
returnProperty String The name of the property to set with result of expression or function call. Note: if this attribute is set, the expression must return a value. n/a No
level String Control the level at which phplint reports status messages. One of error, warning, info, verbose, debug. info No

Supported Nested Tags

PropertyTask

With PropertyTask, you can define user properties in your build file.

Important note about scope: when the <property> tag is called inside a <phingcall> tag, any properties are set in a new local scope. Thus, any properties or other variables set inside that scope will cease to exist (or revert to their previous value) once the parent <phingcall> tag completes.

Example

<property name="strings.test" value="Harr harr, more power!" />
<echo message="${strings.test}" />

<property name="foo.bar" value="Yet another property..." />
<echo message="${foo.bar}" />

<property file="build.properties"  />

<property name="newproperty" value="Hello">
  <filterchain>
    <replaceregexp>
      <regexp pattern="Hello" replace="World" ignoreCase="true"/>
    </replaceregexp>
  <filterchain>
</property>

Attributes

Name Type Description Default Required
name String The name of the Property. n/a Yes (unless using file)
value String The value of the Property. n/a Yes (unless using file)
override Boolean Whether to force override of existing value. false No
file String Path to properties file. n/a No
prefix String Used when properites are loaded from file. Prefix is applied to properties loaded from specified file. A "." is appended to the prefix if not specified. n/a No
environment String The prefix to use when retrieving environment variables. * Thus if you specify environment="myenv" you will be able to access OS-specific * environment variables via property names "myenv.PATH" or "myenv.TERM". n/a No
refid String A reference to a previously defined propeprty n/a No
fallback String If a reference cannot be found within the current project scope this attribute specifies a fallback project scope. n/a No

Supported Nested Tags:

PropertyPromptTask

PropertyPromptTask is a simple task to read in user input into a property. If you need something more advanced, see the InputTask.

Example

<propertyprompt propertyName="someprop" defaultValue="/var/www"
		promptText="Enter your web root" />
<echo>${someprop}</echo>

Attributes

Name Type Description Default Required
propertyName String The name of the Property to set. n/a Yes
promptText String The text to use for the prompt. n/a Yes
promptCharacter String The character to use after the prompt. ? No
defaultValue String A default value to use (if user just hits enter). n/a No
useExistingValue String Whether existing property should be used if available. (This will result in user only being prompted if the propertyName property is not already set.) false No

ReflexiveTask

The ReflexiveTask performs operations on files. It is essentially a convenient way to transform (using filter chains) files without copying them.

Example

<reflexive>
  <fileset dir=".">
    <include pattern="*.html">
  </fileset>
  <filterchain>
    <replaceregexp>
      <regexp pattern="\r(\n)" replace="\1"/>
    </replaceregexp>
  </filterchain>
</reflexive>

Attributes

Name Type Description Default Required
file String A single file to be processed. n/a Yes (unless <fileset> provided)

Supported Nested Tags:

ResolvePathTask

The ResolvePathTask turns a relative path into an absolute path, with respect to specified directory or the project basedir (if no dir attribute specified).

This task is useful for turning a user-defined relative path into an absolute path in cases where buildfiles will be called in different directories. Without this task, buildfiles lower in the directory tree would mis-interpret the user-defined relative paths.

Example

<property name="relative_path" value="./dirname"/>

<resolvepath propertyName="absolute_path" file="${relative_path}"/>

<echo>Resolved [absolute] path: ${absolute_path}</echo>

Attributes

Name Type Description Default Required
file String The file or directory path to resolve. n/a Yes
dir File The base directory to use when resolving "file". project.basedir No
propertyName String The name of the property to set with resolved (absolute) path. n/a Yes
level String Control the level at which status messages are reported. One of error, warning, info, verbose, debug. verbose No

TaskdefTask

With the TaskdefTask you can import a user task into your buildfile.

Example

<!-- Includes the Task named "ValidateHTMLTask" and makes it available by
     <validatehtml> -->
<taskdef classname="user.tasks.ValidateHTMLTask" name="validatehtml" />

<!-- Includes the Task "RebootTask" from "user/sometasks" somewhere inside
     the $PHP_CLASSPATH -->
<taskdef classname="user.sometasks.RebootTask" name="reboot" />

<!-- Includes all tasks from the property file. Each line in the property 
file defines a task in the format: name=path.to.Task -->
<taskdef file="/path/to/mytasks.properties" />

NB: Taskdef now supports the PEAR-style naming convention to define and load tasks:

<taskdef name="sampletask" classname="Dir_Subdir_SampleTask"/>

will load class Dir_Subdir_SampleTask from file Dir/Subdir/SampleTask.php.

Attributes

Name Type Description Default Required
classname String The path to the class that defines the TaskClass. n/a Yes, unless the file attribute has been specified.
name String The name the task is available as after importing. If you specify "validate", for example, you can access the task imported here with <validate>. n/a Yes, unless the file attribute has been specified.
file String Name of the file to load definitions from. n/a No
classpath String The classpath to use when including classes. This is added to PHP's include_path. n/a No
classpathref String Reference to classpath to use when including classes. This is added to PHP's include_path. n/a No

Supported Nested Tags

TouchTask

The TouchTask works like the Unix touch command: It sets the modtime of a file to a specific time. Default is the current time.

Example

<touch file="README.txt" millis="102134111" />

<touch file="COPYING.lib" datetime="10/10/1999 09:31 AM" />

Attributes

Name Type Description Default Required
file String The file which time is to be changed. n/a Yes, or nested <fileset> tag
datetime DateTime The date and time the mtime of the file is to be set to. The format is "MM/DD/YYYY HH:MM AM or PM" now No
millis Integer The number of milliseconds since Midnight Jan 1 1970 (Unix epoche). now No

Supported Nested Tags

TryCatchTask

This task is a wrapper task that lets you run tasks(s) when another set of tasks fails, mirroring PHP's try/catch functionality (with the addition of a finally block)

The tasks inside of the try block will always be run. If one of them throws a BuildException, the following things can happen:

If a finally block is present, the nested tasks will be run regardless of whether the tasks in the try block have thrown an exception or not.

This task was inspired by http://ant-contrib.sourceforge.net/tasks/tasks/trycatch.html.

Example

<trycatch property="foo">
    <try>
        <fail>Tada!</fail>
    </try>

    <catch>
        <echo>In catch.</echo>
    </catch>
		                
    <finally>
        <echo>In finally.</echo>
    </finally>
</trycatch>

<echo>As property: ${foo}</echo>

Attributes

Name Type Description Default Required
property String Name of a property that will receive the message of the exception that has been caught (if any) n/a No

TstampTask

Sets the DSTAMP, TSTAMP, and TODAY properties in the current project. By default, the DSTAMP property is in the format "%Y%m%d", TSTAMP is in the format "%H%M", and TODAY is in the format "%B %d %Y". Use the nested <format> element to specify a different format.

These properties can be used in the build-file, for instance, to create time-stamped filenames, or used to replace placeholder tags inside documents to indicate, for example, the release date. The best place for this task is probably in an initialization target.

Examples

<tstamp/>

sets the standard DSTAMP, TSTAMP, and TODAY properties according to the default formats.

<tstamp>
  <format property="DATE" pattern="%c" locale="nl_NL"/>
</tstamp>

sets the standard properties as well as the property DATE with the date/time pattern "%c" using the Dutch locale.

<tstamp prefix="start"/>

sets three properties with the standard formats, prefixed with "start.": start.DSTAMP, start.TSTAMP, and start.TODAY.

Attributes

Name Type Description Default Required
prefix String Prefix used for all properties set. n/a No

Supported Nested Tags

TypedefTask

With the TypedefTask you can import a user type into your buildfile.

Example

<!-- Includes the Type named "CustomProject" and makes it available by
     <cproject> -->
<taskdef classname="user.types.CustomProject" name="cproject" />

Attributes

Name Type Description Default Required
classname String The path to the class that defines the type class. n/a Yes
name String The name the type is available as after importing. If you specify "cproject", for example, you can access the type imported here with <cproject>. n/a Yes
classpath String The classpath to use when including classes. This is added to PHP's include_path. n/a No
classpathref String Reference to classpath to use when including classes. This is added to PHP's include_path. n/a No

Supported Nested Tags

UpToDateTask

UpToDateTask tests if a resource/file is set and sets a certain property to a certain value if it exists.

<uptodate property="propelBuild.notRequired" targetfile="${deploy}/propelClasses.tgz" >
  <fileset dir="${src}/propel">
    <include="**/*.php"/>
  </fileset>
</uptodate>

sets the property propelBuild.notRequired to true if the ${deploy}/propelClasses.tgz file is more up-to-date than any of the PHP class files in the ${src}/propel directory.

Parameters

Name Type Description Default Required
property string Name of the property that is to be set. n/a Yes
value String The value the propert is to be set to. "true" No
srcfile String The file to check against target file(s). n/a Yes (or nested fileset)
targetfile String The file for which we want to determine the status. n/a Yes (or nested mapper)

Supported Nested Tags

 

XsltTask

With XsltTask, you can run a XSLT tranformation on an XML file. Actually, XsltTask extends CopyTask, so you can use all the elements allowed there.

XsltTask is implemented by means of the XsltFlter and hence relies on PHP5 XSLT support via (libxslt) which must be available in php5. The XsltTask is equivalent to running command line xsltproc since that is a frontend for libxslt.

Example

<!-- Transform docbook with an imaginary XSLT file -->
<xslt todir="/srv/docs/phing" style="dbk2html.xslt" >
  <fileset dir=".">
    <include name="**/*.xml" />
  </fileset>
</xslt>

Attributes

Name Type Description Default Required
style String The path where the Xslt file is located n/a Yes
resolvedocumentexternals Boolean Whether to resolve entities in the XML document. (see this link for details) false No
resolvestylesheetexternals Boolean Whether to resolve entities in the stylesheet. false No

Note: You can also use all the attributes available for CopyTask.

Suppported Nested Elements

Note: You can use all the elements also available for CopyTask.

Additionally, you can use <param> tags with a name and a expression (or value alias) attribute. These parameters are then available from within the xsl style sheet.