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 <phplint> tag, for example, you will want to look at the reference of PhpLintTask.

DbDeployTask

The DbDeployTask creates .sql files for making revisions to a database, based on dbdeploy conventions centering around a changelog table in the database. See rules for using dbdeploy for more information. You will need a changelog table like so:

CREATE TABLE changelog (
  change_number BIGINT NOT NULL,
  delta_set VARCHAR(10) NOT NULL,
  start_dt TIMESTAMP NOT NULL,
  complete_dt TIMESTAMP NULL,
  applied_by VARCHAR(100) NOT NULL,
  description VARCHAR(500) NOT NULL
)

Example

<taskdef name="dbdeploy" classname="phing.tasks.ext.dbdeploy.DbDeployTask"/>

<dbdeploy
  url="sqlite:${project.basedir}/data/db.sqlite">
  userid="dbdeploy"
  password="dbdeploy"
  dir="${project.basedir}/data/dbdeploy/deltas"
/>

The above example uses a sqlite database and delta scripts located in dbdeploy/deltas in the project base dir.

Attributes

Name Type Description Default Required
url String PDO connection url n/a Yes
userid String DB userid to use for accessing the changelog table none As required by db
password String DB password to use for accessing the changelog table none As required by db
dir String Directory containing dbdeploy delta scripts none Yes
outputfile String Filename in which deployment SQL will be generated dbdeploy_deploy.sql No
undooutputfile String Filename in which undo SQL will be generated dbdeploy_undo.sql No
deltaset String deltaset to check within db Main No
lastchangetoapply Integer Highest-numbered delta script to apply to db 999 No

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
   binary="true"
   copy="*.ini config/*"
   encode="*.inc licenses/license.key"
   encrypt="*.tpl *.xml"
   encrypt="more"
   fromdir="files"
   ignore="*.bak RCS/ *~ docs/"
   ioncubepath="/usr/local/ioncube"
   keep="docs/README"
   licensepath="mylicense.txt"
   optimize="max"
   passphrase="mypassphrase"
   phpversion="4"
   targetoption="replace"
   todir="encoded"
   withoutruntimeloadersupport="true">
  <comment>A project encoded with the ionCube encoder.</comment>
</ioncubeencoder>

Attributes

Name Type Description Default Required
allowedserver String Restricts the encoded files to particular servers and/or domains. Consult the IonCude documentation for more information. none No
binary Boolean Whether to save encoded files in binary format (default is ASCII format) false No
copy String Specifies files or directories to exclude from being encoded or encrypted and copy them to the target directory (separated by space). none No
encode String Specifies additional file patterns, files or directories to encode, or to reverse the effect of copy none No
encrypt String Specify files or directories (space separated list) that are to be encrypted. none No
expirein String Sets a period in seconds (s), minutes (m), hours (h) or days (d) after which the files expire. Accepts: 500s or 55m or 24h or 7d none No
expireon String Sets a YYYY-MM-DD date to expire the files. none No
fromdir String Path containing source files none Yes
ignore String Set files and directories to ignore entirely and exclude from the target directory (separated by space). none Yes
ioncubepath String Path to the ionCube binaries /usr/local/ioncube No
keep String Set files and directories not to be ignored (separated by space)./td> none No
licensepath String Path to the license file that will be used by the encoded files none No
nodoccomments String Omits documents comments ( /** ... */ ) from the encoded files. none No
obfuscation-key String The obfuscation key must be supplied when using the obfuscate option none No
obfuscate String The Encoder can obfuscate the names of global functions, the names of local variables in global functions, and line numbers. Use either all or any of functions, locals or linenos separated by a space. none No
optimize String Controls the optimization of the encoded files, accepts either more or max none No
passphrase String The passphrase to use when encoding with a license file none No
phpversion Integer The PHP version to use 5 No
targetoption String Option to use when target directory exists, accepts replace, merge, update and rename none No
todir String Path to save encoded files to none Yes
withoutruntimeloadersupport Boolean Wether to disable support for runtime initialization of the ionCube Loader false No

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

PDOSQLExecTask

The PDOSQLExecTask executes SQL statements using PDO.

Examples

<pdo url="pgsql:host=localhost dbname=test">
  <fileset dir="sqlfiles">
	  <include name="*.sql"/>
  </fileset>
</pdo>
<pdo url="mysql:host=localhost;dbname=test" userid="username" password="password">
  <transaction src="path/to/sqlfile.sql"/>
  <formatter type="plain" outfile="path/to/output.txt"/>
</pdo>

Attributes

Name Type Description Default Required
url String PDO connection URL (DSN) none Yes
userid String Username for connection (if it cannot be specified in URL) none No
password String The password to use for the connection (if it cannot be specified in URL) none No
encoding String The database encoding. none No
src File A single source file of SQL statements to execute. none No
onerror String The action to perform on error (continue, stop, or abort) abort No
delimiter String The delimeter to separate SQL statements (e.g. "GO" in MSSQL) ; No
delimitertype String The delimiter type ("normal" or "row"). Normal means that any occurence of the delimiter terminate the SQL command whereas with row, only a line containing just the delimiter is recognized as the end of the command. normal 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.

Note that this task creates a version 1 package.xml file.

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

PearPackage2Task

With the PearPackage2Task, you can create a version 2 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_PackageFileManager2 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.

Note that Travis Swicegood has created a more complete implementation of this functionality which can be found here: http://pear.domain51.com/index.php?package=Phing_d51PearPkg2Task.

Example

<pearpkg2 name="phing" dir="${build.src.dir}">
   <option name="outputdirectory" value="./build"/>
<option name="packagefile" value="package2.xml"/>
<option name="packagedirectory" value="./${build.dist.dir}"/>
<option name="baseinstalldir" value="${pkg.prefix}"/>
<option name="channel" value="my.pear-channel.com"/>
<option name="summary" value="${pkg.summary}"/>
<option name="description" value="${pkg.description}"/>
<option name="apiversion" value="${pkg.version}"/>
<option name="apistability" value="beta"/>
<option name="releaseversion" value="${pkg.version}"/>
<option name="releasestability" value="beta"/>
<option name="license" value="none"/>
<option name="phpdep" value="5.0.0"/>
<option name="pearinstallerdep" value="1.4.6"/>
<option name="packagetype" value="php"/>
<option name="notes" value="${pkg.relnotes}"/>
<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>
</pearpkg2>

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

Supported Nested Tags

PhpDocumentorTask

This task runs phpDocumentor, an 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
target String Alias of destdir ("target" is config param used by PhpDocumentor) n/a
output String Output format (such as HTML:Smarty:PHP). n/a Yes
sourcecode Boolean Generate syntax-highlighted sourcecode file for each file parsed? false No
examplesdir String Path to directory in which to look for example documentation. n/a No
parseprivate Boolean Parse @internal and elements marked private. false No
javadocdesc Boolean JavaDoc-compliant description parsing. Use on/off, default off (more flexibility) false No
quiet Boolean Suppress output to STDOUT. false No
packageoutput String Output documentation only for selected packages. Use a comma-delimited list n/a No
ignoretags String Comma-separated list of tags to ignore (@package, @subpackage, @access and @ignore may not be ignored). n/a No
defaultpackagename String name to use for the default package. If not specified, uses 'default' n/a No
defaultcategoryname String name to use for the default category. If not specified, uses 'default' n/a No
pear Boolean Treat parse dirs as PEAR repository? (package is directory, _members are @access private) false No

Supported Nested Tags

Examples

<phpdoc title="API Documentation"
  destdir="apidocs"
  sourcecode="no"
  output="HTML:Smarty:PHP">
   <fileset dir="./classes">
      <include name="**/*.php" />
   </fileset>
   <projdocfileset dir=".">
      <include name="README" />
      <include name="INSTALL" />
      <include name="CHANGELOG" />
   </projdocfileset>
</phpdoc>

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
haltonfailure Boolean Stop the build process if the linting process. false No
errorproperty String The name of a property that will be set to contain the error string (if any). 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.

SvnCheckoutTask

The SvnCheckoutTask checks out a Subversion repository to a local directory.

Examples

<svncheckout
   svnpath="/usr/bin/svn"
   username="anony"
   password="anony"
   nocache="true"
   repositoryurl="svn://localhost/project/trunk/"
   todir="/home/user/svnwc"/>
<svncheckout
   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
username String A username used to connect to the SVN server none No
password String A password used to connect to the SVN server none No
nocache String Connection credentials will not be cached boolean No
todir String Path to export to none Yes

SvnExportTask

The SvnExportTask exports a Subversion repository to a local directory.

Examples

<svnexport
   svnpath="/usr/bin/svn"
   username="anony"
   password="anony"
   force="true"
   nocache="true"
   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
username String A username used to connect to the SVN server none No
password String A password used to connect to the SVN server none No
force String Force overwrite files if they already exist boolean No
nocache String Connection credentials will not be cached boolean No
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
workingcopy String Working copy directory none Yes
propertyname String Name of property to use svn.lastrevision No

SvnUpdateTask

The SvnCheckoutTask updates a local directory.

Examples

<svnupdate
   svnpath="/usr/bin/svn"
   username="anony"
   password="anony"
   nocache="true"
   todir="/home/user/svnwc"/>
<svnupdate
   svnpath="C:/Subversion/bin/svn.exe"
   todir="C:/projects/svnwc"/>

Attributes

Name Type Description Default Required
svnpath String Path to Subversion binary /usr/bin/svn No
username String A username used to connect to the SVN server none No
password String A password used to connect to the SVN server none No
nocache String Connection credentials will not be cached boolean No
todir String Path to export to none Yes

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" todir="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
todir 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" todir="dest">
  <fileset dir=".">
    <include name="*.zip"/>
  </fileset>
</unzip>

Attributes

Name Type Description Default Required
file String Archive filename n/a No
todir 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.

ZendCodeAnalyzerTask

The ZendCodeAnalyzerTask analyze PHP source files using the Zend Code Analyzer tool that ships with all versions of Zend Studio.

Attributes

Name Type Description Default Required
analyzerPath String Path to Zend Code Analyzer binary n/a Yes
file String Path to PHP source file n/a No
disable String Disable warnings seperated by comma n/a No
enable String Enable warnings separated by comma n/a No

Supported Nested Tags

Example

<analyze analyzerPath="/usr/local/Zend/ZendStudioClient-5.1.0/bin/ZendCodeAnalyzer" file="SomeClass.php"/>

Analyze one PHP source file with all default warnings enabled.

<analyze analyzerPath="/usr/local/Zend/ZendStudioClient-5.1.0/bin/ZendCodeAnalyzer" disable="var-ref-notmodified,if-if-else">
  <fileset dir=".">
    <include name="**/*.php"/>
  </fileset>
</analyze>

Analyze a set of PHP source files and disable a few warnings.

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