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

AdhocTypedefTask

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

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

Supported Nested Tags

• FileList
• 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".

Parameters

CallTargetTask

The CallTargetTask calls a target from the same project. A <project> 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

CopyTask

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.

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

Attributes

Supported Nested Tags

• Fileset
• Filterchain
• Mapper

DeleteTask

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

Example

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

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

Attributes

Supported Nested Tags

• Fileset

EchoTask

This task simply verboses a string.

Example

<echo msg="Phing rocks!" />

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

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

Attributes

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

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

ForeachTask

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.

Example

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

Attributes

InputTask

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

Example

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

Attributes

MkdirTask

Create a directory.

Example

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

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

Attributes

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

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:

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

Attributes

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.text}" />

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

Attributes

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="\n\r" replace="\n"/>
    </replaceregexp>
  </filterchain>
</reflexive>

Attributes

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

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

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

Attributes

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

Attributes

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

TypedefTask

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

Example

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

Attributes

Supported Nested Tags

• classpath

UpToDateTask

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

Supported Nested Tags

• 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"tyle="dbk2html.xslt" >
  <fileset dir=".">
    <include name="**/*.xml" />
  </fileset>
</xslt>

Attributes

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 value attribute. These parameters are then available from within the xsl style sheet.