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.

CoverageMergerTask

The CoverageMergerTask merges code coverage information from external sources with an existing code coverage database.

The format of the code coverage files is expected to be identical to:

file_put_contents('/www/live/testcases/coverage.data', serialize(xdebug_get_code_coverage));

Supported Nested Tags

Example

<coverage-merger>
  <fileset dir="/www/live/testcases">
    <include name="**/*.data"/>
  </fileset>
</coverage-merger>

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

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

Example

<coverage-setup database="./reports/coverage.db">
  <fileset dir="classes">
    <include name="**/*.php"/>
  </fileset>
</coverage-setup>
<phpunit2 codecoverage="true">
  <batchtest>
    <fileset dir="src">
      <include name="*Test.php"/>
    </fileset>
  </batchtest>
</phpunit2>

IoncubeEncoderTask

The IoncubeEncoderTask executes the ionCube encoder (for either PHP4 or PHP5 projects).

For more information on the meaning of the various options please consult the ionCube user guide.

Example

<ioncubeencoder phpversion="4" binary="true" ioncubepath="/usr/local/ioncube"
  targetoption="replace" withoutruntimeloadersupport="true" optimize="max"
  fromdir="files" todir="encoded" licensepath="mylicense.txt" passphrase="mypassphrase">
  <comment>A project encoded with the ionCube encoder.</comment>
</ioncubeencoder>

Attributes

Name Type Description Default Required
phpversion Integer The PHP version to use 5 No
ioncubepath String Path to the ionCube binaries /usr/local/ioncube No
binary Boolean Wether to save encoded files in binary format (default is ASCII format) false No
withoutruntimeloadersupport Boolean Wether to disable support for runtime initialization of the ionCube Loader false No
optimize String Controls the optimization of the encoded files, accepts either more or max none No
licensepath String Path to the license file that will be used by the encoded files none No
passphrase String The passphrase to use when encoding with a license file none No
targetoption String Option to use when target directory exists, accepts replace, merge, update and rename none No
fromdir String Path containing source files none Yes
todir String Path to save encoded files to none Yes

Supported Nested Tags

IoncubeLicenseTask

The IoncubeLicenseTask executes the ionCube make_license program.

For more information on the meaning of the various options please consult the ionCube user guide.

Example

<ioncubelicense ioncubepath="/usr/local/ioncube" licensepath="mylicense.txt" passphrase="mypassphrase">
  <comment>A license file made with the ionCube encoder.</comment>
</ioncubelicense>

Attributes

Name Type Description Default Required
ioncubepath String Path to the ionCube binaries /usr/local/ioncube No
licensepath String Path to the license file that will be generated none No
passphrase String The passphrase to use when generating the license file none No

Supported Nested Tags

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

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

PhpLintTask

The PhpLintTask checks syntax (lint) on one or more PHP source code files.

Attributes

Name Type Description Default Required
file String Path to source file n/a No

Supported Nested Tags

Example

<phplint file="path/to/source.php"/>

Checking syntax of one particular source file.

<phplint>
  <fileset dir="src">
    <include name="**/*.php"/>
  </fileset>
</phplint>

Check syntax of a fileset of source files.

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
errorproperty String Name of property to set (to true) on error. n/a No
failureproperty String Name of property to set (to true) on failure. n/a No

Supported Nested Tags

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.

Important note: using a mechanism such as an "AllTests.php" file to execute testcases will bypass the Phing hooks used for reporting and counting, and could possibly lead to strange results. Instead, use one of more fileset's to provide a list of testcases to execute.

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.

Important note: testclasses that are not explicitly placed in a package (by using a '@package' tag in the class-level DocBlock) are listed under the "default" package.

SvnExportTask

The SvnExportTask exports a Subversion repository to a local directory.

Examples

<svnexport svnpath="/usr/bin/svn" repositoryurl="svn://localhost/project/trunk/" todir="/home/user/svnwc"/>
<svnexport svnpath="C:/Subversion/bin/svn.exe" repositoryurl="svn://localhost/project/trunk/" todir="C:/projects/svnwc"/>

Attributes

Name Type Description Default Required
svnpath String Path to Subversion binary /usr/bin/svn No
repositoryurl String URL of SVN repository none Yes
todir String Path to export to none Yes

SvnLastRevisionTask

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

Examples

<svnlastrevision svnpath="/usr/bin/svn" workingcopy="/home/user/svnwc" propertyname="svn.lastrevision"/>
<svnlastrevision svnpath="C:/Subversion/bin/svn.exe" workingcopy="C:/projects/svnwc" propertyname="svn.lastrevision"/>

Attributes

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

TarTask

The TarTask creates a tarball from a fileset or directory.

Examples

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

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

<tar destfile="phing.tar" basedir="." compression="gzip"/>

The second example uses the basedir attribute to include the contents of that directory (including subdirectories) 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 #1: files are not replaced if they are already present in the archive.

Important note #2: using basedir and fileset simultaneously can result in strange contents in the archive.

Supported Nested Tags

UntarTask

The UntarTask unpacks one or more tar archives.

Examples

<untar file="testtar.tar.gz" destdir="dest">
  <fileset dir=".">
    <include name="*.tar.gz"/>
    <include name="*.tar"/>
  </fileset>
</untar>

Attributes

Name Type Description Default Required
file String Archive filename n/a No
destdir String Directory to unpack the archive(s) to none Yes

Supported Nested Tags

UnzipTask

The UnzipTask unpacks one or more ZIP archives.

Examples

<unzip file="testzip.zip" destdir="dest">
  <fileset dir=".">
    <include name="*.zip"/>
  </fileset>
</unzip>

Attributes

Name Type Description Default Required
file String Archive filename n/a No
destdir String Directory to unpack the archive(s) to none Yes

Supported Nested Tags

XmlLintTask

The XmlLintTask checks syntax (lint) one or more XML files against an XML Schema Definition.

Attributes

Name Type Description Default Required
schema String Path to XSD file n/a Yes
file String Path to XML file n/a No

Supported Nested Tags

Example

<xmllint schema="schema.xsd" file="config.xml"/>

Validate one XML file against one XSD file.

<xmllint schema="schema.xsd">
  <fileset dir=".">
    <include name="**/config.xml"/>
  </fileset>
</xmllint>

Validate more XML files against one XSD file.

ZipTask

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

Examples

<zip destfile="phing.zip">
 <fileset dir=".">
	 <include name="**/**" />
 </fileset>
</zip>

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

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

The second example uses the basedir attribute to include the contents of that directory (including subdirectories) in the archive.

Example

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

Important note: using basedir and fileset simultaneously can result in strange contents in the archive.

Supported Nested Tags