Appendix C: Optional Tasks

This appendix contains a reference of all optional tasks, i.e. tasks that are not directly needed for building projects, but can assist in various aspects of development and deployment.

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.

CoverageReportTask

The CoverageReportTask formats a coverage database into a framed HTML report using XSLT.

Attributes

Name	Type	Description	Default	Required
outfile	String	The location for the intermediate XML file.	coverage.db	Yes

Supported Nested Tags

report

Attributes

Name	Type	Description	Default	Required
styledir	String	The directory where the stylesheets are located.	n/a	Yes
todir	String	The directory where the files resulting from the transformation should be written to.		Yes

Example

<coverage-report outfile="reports/coverage.xml">
  <report todir="reports/coverage" styledir="/home/phing/etc"/>
</coverage-report>

CoverageSetupTask

The CoverageSetupTask prepares a database which can be used to gather code coverage information for unit tests. The code coverage tasks use the Xdebug extension.

Attributes

Name	Type	Description	Default	Required
database	String	The location for the coverage database.	coverage.db	Yes

Supported Nested Tags

fileset

Example

<coverage-setup database="./reports/coverage.db">
  <fileset dir="classes">
    <include name="**/*.php"/>
  </fileset>
</coverage-setup>
<phpunit2>
  <formatter classname="phing.tasks.ext.coverage.CoverageFormatter" usefile="false"/>
  <batchtest>
    <fileset dir="src">
      <include name="*Test.php"/>
    </fileset>
  </batchtest>
</phpunit2>

PearPackageTask

With the PearPackageTask, you can create a package.xml which can be installed using the PEAR installer. Use this in conjunction with the TarTask to completely script the building of a PEAR pacakge.

This task uses the PEAR_PackageFileManager class. In order to be maximally flexible, the majority of options are set generically (using <option> tag) and are set using PEAR_PackageFileManager::setOptions(). Use the <mapping> tag to represent complex values (which are turned into associative arrays and also set using setOptions() method).

Example

<pearpkg name="phing" dir="${build.src.dir}" destFile="${build.base.dir}/package.xml">
<fileset>
  <include name="**"/>
</fileset>
<option name="notes">Sample release notes here.</option>
<option name="description">Package description</option>
<option name="summary">Short description</option>
<option name="version" value="2.0.0b1"/>
<option name="state" value="beta"/>
 <mapping name="maintainers">
  <element>
   <element key="handle" value="hlellelid"/>
   <element key="name" value="Hans"/>
   <element key="email" value="hans@xmpl.org"/>
   <element key="role" value="lead"/>
  </element>
</mapping>
</pearpkg>

Attributes

Name	Type	Description	Default	Required
name	String	The name of the PEAR package.	n/a	Yes
dir	String	The base directory of files to add to package.	n/a	Yes
destFile	String	The file to create.	package.xml in base directory	No

Supported Nested Tags

fileset
option
mapping

PHPDocumentorTask

This task runs phpDocumentor, a auto-documentation tool for PHP similar to Javadoc.

Attributes

Name	Type	Description	Default	Required
title	String	Title for browser window / package index.	n/a	No
destdir	String	Destination directory for output files.	n/a	Yes
sourcepath	String	Specify where to find source files.	n/a	Yes
linksource	Boolean	Generate hyperlinks to source files.	false	No
output	String	Output format (such as HTML:Smarty:PHP).	n/a	Yes
parseprivate	Boolean	Show private members.	false	No

Examples

<phpdoc title="Phing Documentation" destdir="apidocs" sourcepath="classes/phing" output="HTML:Smarty:PHP"/>

PHPUnit2Task

This task runs testcases using the PHPUnit2 framework. It is a functional port of the Ant JUnit task.

Attributes

Name	Type	Description	Default	Required
printsummary	Boolean	Print one-line statistics for each testcase.	false	No
haltonerror	Boolean	Stop the build process if an error occurs during the test run.	false	No
haltonfailure	Boolean	Stop the build process if a test fails (errors are considered failures as well).	false	No

Supported Nested Tags

formatter

The results of the tests can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. The name of the file is predetermined by the formatter and can be changed by the outfile attribute.

There are three predefined formatters - one prints the test results in XML format, the other emits plain text. The formatter named brief will only print detailed information for testcases that failed, while plain gives a little statistics line for all test cases. Custom formatters that implement phing.tasks.ext.PHPUnit2ResultFormatter can be specified.

If you use the XML formatter, it may not include the same output that your tests have written as some characters are illegal in XML documents and will be dropped.

Attributes

Name	Type	Description	Default	Required
type	String	Use a predefined formatter (either xml, plain, or brief).	n/a	One of these is required.
classname	String	Name of a custom formatter class.	n/a	One of these is required.
usefile	Boolean	Boolean that determines whether output should be sent to a file.	true	No
todir	String	Directory to write the file to.	n/a	No
outfile	String	Filename of the result.	Depends on formatter	No

batchtest

Define a number of tests based on pattern matching. batchtest collects the included files from any number of nested <fileset>s. It then generates a test class name for each file that ends in .php

Attributes

Name	Type	Description	Default	Required
prefix	String	A prefix to use for classnames. For example, when a class is named Phing_Test and the corresponding file is Test.php, the prefix would be Phing_.	n/a	No

Supported Nested Tags

classpath
fileset

Examples

<phpunit2>
  <formatter todir="reports" type="xml"/>
  <batchtest>
    <fileset dir="tests">
      <include name="**/*Test*.php"/>
      <exclude name="**/Abstract*.php"/>
    </fileset>
  </batchtest>
</phpunit2>

Runs all matching testcases in the directory tests, writing XML results to the directory reports.

<phpunit2 haltonfailure="true" haltonerror="true">
  <formatter type="plain" usefile="false"/>
  <batchtest>
    <fileset dir="tests">
      <include name="**/*Test*.php"/>
    </fileset>
  </batchtest>
</phpunit2>

Runs all matching testcases in the directory tests, writing plain text results to the console. The build process is aborted if a test fails.

PHPUnit2Report

This task transforms PHPUnit2 xml reports to HTML using XSLT.

Attributes

Name	Type	Description	Default	Required
infile	String	The filename of the XML results file to use.	testsuites.xml	No
format	String	The format of the generated report. Must be noframes or frames.	noframes	No
styledir	String	The directory where the stylesheets are located. They must conform to the following conventions: frames format: the stylesheet must be named phpunit2-frames.xsl. noframes format: the stylesheet must be named phpunit2-noframes.xsl.	n/a	Yes
todir	String	The directory where the files resulting from the transformation should be written to.		Yes

Examples

<phpunit2report infile="reports/testsuites.xml" format="frames" todir="reports/tests" styledir="/home/phing/etc"/>

Generates a framed report in the directory reports/tests using the file reports/testsuites.xml as input.

SvnLastRevisionTask

The SvnLastRevisionTask stores the number of the last revision of a Subversion workingcopy in a property.

Example

<svnlastrevision svnpath="/usr/bin/svn" workingcopy="/home/user/svnwc/" propertyname="svn.lastrevision"/>

Attributes

Name	Type	Description	Default	Required
svnpath	String	Path to Subversion binary	/usr/bin/svn	No
workingcopy	String	Working copy directory	none	Yes
propertyname	String	Name of property to use	svn.lastrevision	No

TarTask

The TarTask creates a tarball from a fileset or directory.

Example

<tar destfile="phing.tar" basedir="." compression="gzip">
 <fileset dir=".">
	 <include name="**/**" />
 </fileset>
</tar>

The above example uses a fileset to determine which files to include in the archive.

Attributes

Name	Type	Description	Default	Required
destfile	String	Tarball filename	n/a	Yes
basedir	String	Base directory to tar (if no fileset specified, entire directory contents will be included in tar)	none	No
compression	String	Type of compression to use (gzip, bzip2, none)	none	No

Important note: files are not replaced if they are already present in the archive.

Supported Nested Tags

fileset

ZipTask

The ZipTask creates a .zip archive from a fileset or directory.

Example

<zip destfile="phing.zip" basedir="."/>

Attributes

Name	Type	Description	Default	Required
destfile	String	.ZIP filename	n/a	Yes
basedir	String	Base directory to zip (if no fileset specified, entire directory contents will be included in the archive)	none	No

Supported Nested Tags

fileset