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.
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));
<coverage-merger> <fileset dir="/www/live/testcases"> <include name="**/*.data"/> </fileset> </coverage-merger>
The CoverageReportTask formats a coverage database into a framed HTML report using XSLT.
Name | Type | Description | Default | Required |
---|---|---|---|---|
outfile | String | The location for the intermediate XML file. | coverage.db | Yes |
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 |
<coverage-report outfile="reports/coverage.xml"> <report todir="reports/coverage" styledir="/home/phing/etc"/> </coverage-report>
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.
Name | Type | Description | Default | Required |
---|---|---|---|---|
database | String | The location for the coverage database. | coverage.db | Yes |
<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>
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.
<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>
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 |
Custom text that is added to the start of each encoded file.
The IoncubeLicenseTask executes the ionCube make_license program.
For more information on the meaning of the various options please consult the ionCube user guide.
<ioncubelicense ioncubepath="/usr/local/ioncube" licensepath="mylicense.txt" passphrase="mypassphrase"> <comment>A license file made with the ionCube encoder.</comment> </ioncubelicense>
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 |
Custom text that is added to the start of each encoded file.
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).
<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>
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 |
This task runs phpDocumentor, a auto-documentation tool for PHP similar to Javadoc.
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 |
<phpdoc title="Phing Documentation" destdir="apidocs" sourcepath="classes/phing" output="HTML:Smarty:PHP"/>
The PhpLintTask checks syntax (lint) on one or more PHP source code files.
Name | Type | Description | Default | Required |
---|---|---|---|---|
file | String | Path to source file | n/a | No |
<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.
This task runs testcases using the PHPUnit2 framework. It is a functional port of the Ant JUnit task.
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 |
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.
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 | |
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 |
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 lists of classes that are (in)directly defined by each file that ends with .php
Name | Type | Description | Default | Required |
---|---|---|---|---|
exclude | String | A list of classes to exclude from the pattern matching. For example, when you have two baseclasses BaseWebTest and BaseMathTest, which are included a number of testcases (and thus added to the list of testclasses), you can exclude those classes from the list by typing exclude="BaseWebTest BaseMathTest". | n/a | No |
classpath | String | Used to define more paths on which - besides the PHP include_path - to look for the test files. | n/a | No |
<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.
This task transforms PHPUnit2 xml reports to HTML using XSLT.
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:
|
n/a | Yes |
todir | String | The directory where the files resulting from the transformation should be written to. | Yes |
<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.
The SvnExportTask exports a Subversion repository to a local directory.
<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"/>
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 |
The SvnLastRevisionTask stores the number of the last revision of a Subversion workingcopy in a property.
<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"/>
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 |
The TarTask creates a tarball from a fileset or directory.
<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.
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.
The UntarTask unpacks one or more tar archives.
<untar file="testtar.tar.gz" destdir="dest"> <fileset dir="."> <include name="*.tar.gz"/> <include name="*.tar"/> </fileset> </untar>
Name | Type | Description | Default | Required |
---|---|---|---|---|
file | String | Archive filename | n/a | No |
destdir | String | Directory to unpack the archive(s) to | none | Yes |
The UnzipTask unpacks one or more ZIP archives.
<unzip file="testzip.zip" destdir="dest"> <fileset dir="."> <include name="*.zip"/> </fileset> </unzip>
Name | Type | Description | Default | Required |
---|---|---|---|---|
file | String | Archive filename | n/a | No |
destdir | String | Directory to unpack the archive(s) to | none | Yes |
The XmlLintTask checks syntax (lint) one or more XML files against an XML Schema Definition.
Name | Type | Description | Default | Required |
---|---|---|---|---|
schema | String | Path to XSD file | n/a | Yes |
file | String | Path to XML file | n/a | No |
<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.
The ZipTask creates a .zip archive from a fileset or directory.
<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.
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.