# 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

- FileList
- FileSet
- FilterChain

## 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

### Supported Nested Tags

- filepath

## 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

- fileset

## 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 | 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 in error message in case of a failure | true | No

### Supported Nested Tags

- fileset

## 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

## 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 | If set to true, the target file will be overwritten. | 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. | 0755 | No
haltonerror | Boolean | If set to true, halts the build when errors are encountered. | true | No

### Supported Nested Tags

- Fileset
- Filelist
- Filterchain
- Mapper

## 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, more complex:

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

### 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
setfailonerror | 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

### Supported Nested Tags

- command

## 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 suers 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 | No
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. | true | No
includeemptydirs | Boolean | Determines if empty directories are also to be deleted. | false | No

### Supported Nested Tags

- Fileset

## 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

- Fileset

## 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

- arg

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  value | String | A single command-line argument; can contain space characters. | 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

## ExitTask

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

### Example

    <-- 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!" />

### Attributes

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

## 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 | 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
absparam | string | The name of the absolute pathparameter to pass the tokens in as to the target (used while processing nested filesets). | n/a | Yes
delimiter | string | The delimiter string that separates the values in the "list" parameter. The default is ",". | , | No

### Supported Nested Tags

- Fileset
- Mapper

## 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.

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 property 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="...">
      <php function="dirname" returnProperty="imported.basedir">
        <param value="${phing.file.imported}"/>
      </php>
      <property file="${imported.basedir}/imported.properties"/>
    </project>

As explained above `${phing.file.imported}` stores the path of the build script, that defines the project called imported, (in short it stores the path to imported.xml) and <php function="dirname"> takes 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

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

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
classpath | String | the new include path[s] | n/a | Yes

## 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 | 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

## 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:

- filterchain

## 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. | 0755 | 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

- Fileset

### 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 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.

### Example

    <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>

### 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

## 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

### Supported Nested Tags

- param

## PropertyTask

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

### 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"  />

### 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

## 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="\n"/>
        </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:

- fileset
- filterchain

## 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

## 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

- classpath

## 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

- fileset

## 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

- format

  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.

  ### Attributes

  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

## 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

- classpath

## 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

- FileList
- FileSet
- Mapper

## 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.

### 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.