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.
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.
Name | Type | Description | Default | Required |
---|---|---|---|---|
name | String | Name of XML tag that will represent this task. | n/a | Yes |
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.
Name | Type | Description | Default | Required |
---|---|---|---|---|
name | String | Name of XML tag that will represent this datatype.. | n/a | Yes |
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!
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 |
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".
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 |
The PhingCallTask calls a target from the same Phing project. A <phingcall> tag may contain <property> tags that define new properties. In the following example, the properties property1 and foo are defined and only accessible inside the called target.
However, this will only work if the properties are not yet
set outside the "phingcall"
tag.
<target name="foo"> <phingcall target="bar"> <property name="property1" value="aaaaa" /> <property name="foo" value="baz" /> </phingcall> </target> <target name="bar" depends="init"> <echo message="prop is ${property1} ${foo}" /> </target>
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 |
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.
<condition property="isMacOrWindows"> <or> <os family="mac"/> <os family="windows"/> </or> </condition>
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 |
The phing Copy Task. Copies a file or directory to a new file or directory. 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.
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. Mappers and Filterchains are also supported by CopyTask, so you can do almost everything that needs processing the content of the files or the filename.
Notice: CopyTask does not allow self copying, i.e. copying a file to the same name for security reasons.
<copy todir="/tmp/backup" > <fileset dir="."> <include name="**/*.txt" /> <include name="**/*.doc" /> <include name="**/*.swx" /> </fileset> </copy>
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. | n/a | Yes (or tofile) |
overwrite | Boolean | If set to true, the target file will be overwritten. | false | No |
tstamp | 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 |
Deletes a file or directory, or set of files defined by a fileset. See Appendix D for information on Filesets.
<-- 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>
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 |
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 | Yes |
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 | Yes |
failonerror | Boolean | If this attribute is set to true, DeleteTask will verbose on errors but the build process will not be stopped. | true | Yes |
includeemptydirs | Boolean | Determines if empty directories are also to be deleted. | false | False |
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
<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>
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. | warning | No |
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.
<-- 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" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
command | String | The command that is to be executed. | n/a | Yes |
dir | String | The directory the command is to be executed in. | n/a | No |
os | String | Only execute if os.name 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 | Wether to passthru the output. | FALSE | No |
spawn | Boolean | Wether to spawn unix programs to the background, redirecting stdout. | FALSE | No |
checkreturn | Boolean | Wether to check the return code of the program, throws a BuildException when returncode != 0. | FALSE | No |
Causes the current build script execution to fail and the script to exit with an (optional) error message.
<-- Exit w/ 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!" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
message | String | The message to display (reason for script abort). | "No Message" | 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 |
The foreach task iterates over a list, a list of paths, or both. If both, list and paths, are specified, the list will be evaluated first. Nested paths are evaluated in the order they appear in the task.
<!-- loop through languages, and call buildlang task with setted param --> <property name="langauges" value="en,fr,de" /> <foreach list="${languages}" param="lang" target="buildlang" />
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 | Yes |
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 |
delimiter | string | The delimiter string that separates the values in the "list" parameter. The default is ",". | , | No |
Perform some tasks based on whether a given condition holds true or not.
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.
<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>
Sets the PHP include_path configuration option for the duration of this phing run.
<includepath classpath="new/path/here" /> <includepath classpath="path1:path2" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
classpath | String | the new include path[s] | n/a | Yes |
The InputTask can be used to interactively set property values based on input from the console (or other Reader).
<!-- 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>
Name | Type | Description | Default | Required |
---|---|---|---|---|
propertyName | String | The name of the property to set. | n/a | Yes |
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 | No |
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 |
Create a directory.
<-- Create a temp directory --> <mkdir dir="/tmp/foo" /> <-- Using mkdir with a property --> <mkdir dir="${dirs.install}/tmp" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
dir | String | The directory that is to be created. | n/a | Yes |
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.
<-- 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" />
For further documentation, see CopyTask, since MoveTask only is a child of CopyTask and inherits all attributes.
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).
<-- 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>
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 |
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 |
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.
<php function="crypt" returnProperty="enc_passwd"> <param value="${auth.root_passwd}"/> </php>
<php expression="3 + 4" returnProperty="sum"/>
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. | n/a | No |
With PropertyTask, you can define user properties in your build file.
<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" />
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 |
PropertyPromptTask is a simple task to read in user input into a property. If you need something more advanced, see the InputTask.
<propertyprompt propertyName="someprop" defaultValue="/var/www" promptText="Enter your web root" /> <echo>${someprop}</echo>
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 |
The ReflexiveTask performs operations on files. It is essentially a convenient way to transform (using filter chains) files without copying them.
<reflexive> <fileset dir="."> <include pattern="*.html"> </fileset> <filterchain> <replaceregexp> <regexp pattern="\n\r" replace="\n"/> </replaceregexp> </filterchain> </reflexive>
Name | Type | Description | Default | Required |
---|---|---|---|---|
file | String | A single file to be processed. | n/a | Yes (unless <fileset> provided) |
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.
<property name="relative_path" value="./dirname"/> <resolvepath propertyName="absolute_path" file="${relative_path}"/> <echo>Resolved [absolute] path: ${absolute_path}</echo>
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 |
With the TaskdefTask you can import a user task into your buildfile.
<!-- 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" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
classname | String | The path to the class that defines the TaskClass. | n/a | Yes |
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 |
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 |
The TouchTask works like the Unix touch command: It sets the modtime of a file to a specific time. Default is the current time.
<touch file="README.txt" millis="102134111" /> <touch file="COPYING.lib" datetime="10/10/1999 09:31 AM" />
Name | Type | Description | Default | Required |
---|---|---|---|---|
file | String | The file which time is to be changed. | n/a | No |
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 millisecons since midnight Jan 1 1970 (Unix epoche). | now | No |
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.
<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.
Name | Type | Description | Default | Required |
---|---|---|---|---|
prefix | String | Prefix used for all properties set. | n/a | No |
The Tstamp task supports a <format> nested element that allows a property to be set to the current date and time in a given format. The date/time patterns are as defined in the PHP strftime() function.
Name | Type | Description | Default | Required |
---|---|---|---|---|
property | String | The property to receive the date/time string in the given pattern. | n/a | Yes |
classname | String | The date/time pattern to be used. The values are as defined by the PHP strftime() function. | n/a | Yes |
locale | String | The locale used to create date/time string. For more information see the PHP setlocale() function. | n/a | No |
With the TypedefTask you can import a user type into your buildfile.
<!-- Includes the Type named "CustomProject" and makes it available by <cproject> --> <taskdef classname="user.types.CustomProject" name="cproject" />
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 |
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" > <srcfiles dir= "${src}/propel" includes="**/*.php"/> </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 srcfiles) |
targetfile | String | The file for which we want to determine the status. | n/a | Yes (or nested mapper) |
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.
<!-- Transform docbook with an imaginary XSLT file --> <xslt todir="/srv/docs/phing" style="dbk2html.xslt" > <fileset dir="."> <include name="**/*.xml" /> </fileset> </xslt>
Name | Type | Description | Default | Required |
---|---|---|---|---|
style | String | The path where the Xslt file is located | n/a | Yes |
Note: You can also use all the attributes available for CopyTask.
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.