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".
NB: the Available task can also be used as a condition.
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 |
Sets the mode of a file or directory.
<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.
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 |
Changes the owner of a file or directory.
<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" />
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 |
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 |
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.
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.
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.
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 |
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.
<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" />
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 |
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.
<!-- 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" />
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 |
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 (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 |
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.
<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. | info | 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 | 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 |
Name | Type | Description | Default | Required |
---|---|---|---|---|
value | String | A single command-line argument; can contain space characters. To pass an empty argument, enclose two double quotes in single quotes ('""'). | n/a | One of these |
file | String | The name of a file as a single command-line argument; will be replaced with the absolute filename of the file. | n/a | |
path | String | A string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Ant will convert it to the platform's local conventions. | n/a | |
line | String | A space-delimited list of command-line arguments. | n/a |
Causes the current build script execution to fail (throwing a BuildException) and the script to exit with an (optional) error message.
<-- 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!" />
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 |
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.
<!-- 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>
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 |
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>
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.
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.
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.
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).
<import file="path/to/build.xml"/> <import file="path/to/build.xml" optional="true"/>
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 |
Sets the PHP include_path configuration option for the duration of this phing run.
<includepath classpath="new/path/here" /> <includepath classpath="path1:path2" />
<path id="project.class.path"> <pathelement dir="lib/"/> <pathelement dir="ext/"/> </path> <includepath classpathref="project.class.path" />
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 |
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 | 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 |
The LoadFileTask loads the contents of a (text) file into a single property.
<loadfile property="version" file="version.txt"/>
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 |
Creates a directory, including any necessary but non-existent parent directories. Does nothing if the directory already exists.
<-- 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 |
mode | Integer | The mode to create the directory with. | From umask | No |
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 |
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.
<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>
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 |
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"/>
<php expression="echo 'test';">
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 |
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.
<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>
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 |
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="\r(\n)" replace="\1"/> </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 |
level | String | Control the level at which status messages are reported. One of error, warning, info, verbose, debug. | verbose | No |
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" /> <!-- 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.
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 |
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 | 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 |
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.
<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>
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 |
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" > <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) |
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.
<!-- 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 |
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.
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.