# 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

- fileset

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

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

### Attributes

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

### Supported Nested Tags

- classpath
- fileset

### Example

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

## CoverageThresholdTask

This task validates the code coverage database and will stop the build cycle if any class or method or entire project's coverage is lower than the specified threshold.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
database | String | The location of the coverage database. (This is optional if CoverageSetupTask has run before) | n/a | No
perProject | Integer | The minimum code coverage for the entire project. | 25 | No
perClass | Integer | The minimum code coverage for any class. | 25 | No
perMethod | Integer | The minimum code coverage for any method. | 25 | No
verbose | Boolean | Whether to enable detailed logging or not. | false | No

### Supported Nested Tags

- classpath

### Example

    <coverage-threshold database="./reports/coverage.db"/>

Validates an optional code coverage database against the default thresholds.

    <coverage-threshold
        perProject="50"
        perClass="60"
        perMethod="70"/>

Validates the code coverage database (from CoverageSetupTask) against the specified thresholds.

## ExportPropertiesTask

Exports all defined properties to a specified file.

### Example

    <exportproperties targetfile="output.props" />

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
targetfile | String | Target file for saved properties | n/a | Yes
disallowedPropertyPrefixes | String | Exclude properties starting with these prefixes (separated by , | 'host.', 'phing.', 'os.', 'php.', 'line.', 'env.', 'user.' | No

## FileHashTask

Calculates either MD5 or SHA1 hash value of a file and stores the value as a hex string in a property.

### Example

    <filehash file="${builddir}/${tarball}.tar.${compression}" />
    <echo "Hashvalue is; ${filehashvalue}" />

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | Filename | n/a | Yes
hashtype | Integer | Specifies what hash algorithm to use. 0=MD5, 1=SHA1 | 0 | No
propertyname | String | Name of property where the hash value is stored | filehashvalue | No

## FileSizeTask

Stores the size of a specified file in a property. The file size is returned in bytes.

### Example

    <filesize file="${builddir}/${tarball}.tar.${compression}" />
    <php expression="floor(${filesize}/1024)" returnProperty="ksize" />
    <php expression="floor(${filesize}/1024/1024)" returnProperty="msize" />
    <echo msg="Filesize is: ${ksize} kB"/>
    <echo msg="Filesize is: ${msize} MB"/>

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | Filename | n/a | Yes
propertyname | String | Name of property where the file size is stored | filesize | No

## FtpDeployTask

Deploys a set of files to a remote FTP server.

### Example

    <ftpdeploy
      host="${ftp.host}"
      port="${ftp.port}"
      username="${ftp.username}"
      password="${ftp.password}"
      dir="${ftp.dir}"
      mode="${ftp.mode}">
      <fileset dir=".">
        <include name="**"/>
        <exclude name="phing"/>
        <exclude name="build.xml"/>
        <exclude name="images/**.png"/>
        <exclude name="images/**.gif"/>
        <exclude name="images/**.jpg"/>
      </fileset>
    </ftpdeploy>

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
host | String | The hostname of the remote server. | none | Yes
port | Boolean | The port of the remote server. | 21 | No
username | String | The username to use when logging in to the remote server. | none | Yes
password | String | The password to use when logging in to the remote server | none | Yes
dir | String | Directory on the remote server. | none | No
mode | String | The transfer mode to use, either ascii or binary. | binary | No
clearfirst | Boolean | Delete all files in the remote directory before uploading | false | No

### Supported Nested Tags

- fileset

  The files to deploy

## HttpRequestTask

This task will make an HTTP request to the provided URL and match the response against the provided regular expression. If an regular expression is provided and doesn't match the build will fail. You need an installed version of HTTP_Request2 to use this task.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
url | String | The request URL | n/a | Yes
responseRegex | String | The regular expression for matching the response | n/a | No
authUser | String | The authentication user name | n/a | No
authPassword | String | The authentication password | n/a | No
authScheme | String | The authentication scheme | basic | No
verbose | Boolean | Whether to enable detailed logging | false | No
observerEvents | String | Comma-separated list of events to log when verbose is set to true | connect, sentHeaders, sentBodyPart, receivedHeaders, receivedBody, disconnect | No

### Supported Nested Tags

- config

  Holds additional config data. See HTTP_Request2 for supported values.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  name | String | Config parameter name | n/a | Yes
  value | Mixed | Config value | n/a | Yes

- header

  Holds additional header name and value.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  name | String | Header name | n/a | Yes
  value | String | Header value | n/a | Yes

### Examples

     <http-request url="http://my-production.example.com/check-deployment.php"/>

Just perform a HTTP request to the given URL.

     <http-request
       url="http://my-production.example.com/check-deployment.php"
       responseRegex="/Heartbeat/"
       verbose"true"
       observerEvents="connect, disconnect"/>

Perform a HTTP request to the given URL and matching the response against the given regex pattern. Enable detailed logging and log only the specified events.

     <http-request url="http://my-production.example.com/check-deployment.php">
       <config name="adapter" value="HTTP_Request2_Adapter_Curl"/>
       <header name="user-agent" value="Phing HttpRequestTask"/>
     </http-request>

Perform a HTTP request to the given URL. Setting request adapter to curl instead of socket. Setting an additional header.

## 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"
       fromdir="files"
       ignore="*.bak RCS/ *~ docs/"
       ioncubepath="/usr/local/ioncube"
       keep="docs/README"
       licensepath="mylicense.txt"
       optimize="max"
       passphrase="mypassphrase"
       phpversion="4"
       noshortopentags="false"
       targetoption="replace"
       todir="encoded"
       withoutruntimeloadersupport="true"
       callbackfile="errhandler.php"
       obfuscationexlusionsfile="obfex.txt">
      <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). | 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
noshortopentags | Boolean | Wether to disable support for short PHP tags | false | No
callbackfile | String | Path to callback file (.php) | n/a | No
obfuscationexclusionsfile | String | Path to obfuscation exclusions file | n/a | No

### Supported Nested Tags

- comment

  Custom text that is added to the start of each encoded file.

## 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"
       allowedserver="00:06:4F:01:8F:2C"
       expireon="2010-09-01"
       expirein="7d">
      <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
allowedserver | String | Restricts the license to particular servers and/or domains. Consult the IonCude documentation for more information. | none | No
expirein | String | Sets a period in seconds (s), minutes (m), hours (h) or days (d) after which the license expires. Accepts: 500s or 55m or 24h or 7d. | none | No
expireon | String | Sets a YYYY-MM-DD date to expire the license. | none | No

### Supported Nested Tags

- comment

  Custom text that is added to the start of each encoded file.

## JslLintTask

The JslLintTask uses the Javascript Lint program to check the sytax on one or more JavaScript source code files.

NB: the Javascript lint program must be in the system path!

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
executable | String | Path to JSL executable | jsl | No
file | String | Path to source file | n/a | No
haltonfailure | Boolean | Stop the build process if the linting process encounters an error. | false | No
showwarnings | Boolean | Sets the flag if warnings should be shown. | true | No
cachefile | String | If set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely change | none | No
conffile | String | Path to JSL config file | none | No

### Supported Nested Tags

- fileset

### Example

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

Checking syntax of one particular source file.

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

Check syntax of a fileset of source files.

## JsMinTask

The JsMinTask minifies JavaScript files using JsMin. JsMin is bundled with Phing and does not need to be installed separately.

For more information on minifying JavaScript files see Douglas Crockford's introduction to minifying JavaScript files.

### Example

    <jsMin targetDir="docroot/script/minified" failOnError="false">
      <fileset dir="docroot/script">
        <include name="**/*.js"/>
      </fileset>
    </jsMin>

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
targetDir | String | Path where to store minified JavaScript files | none | Yes
failonerror | Boolean | Whether an error while minifying a JavaScript file should stop the build or not | false | No

### Supported Nested Tags

- fileset

  JavaScript files to be minified.

## PatchTask

The PatchTask uses the patch program to apply diff file to originals.

NB: the patch program must be in the system path!

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
patchfile | String | File that includes the diff output | n/a | Yes
originalfile | String | File to patch. If not specified Task tries to guess it from the diff file | none | No
destfile | String | File to send the output to instead of patching the file in place | none | No
backups | Boolean | Keep backups of the unpatched files | false | No
quiet | Boolean | Work silently unless an error occurs | false | No
reverse | Boolean | Assume patch was created with old and new files swapped | false | No
ignorewhitespace | Boolean | Ignore whitespace differences | false | No
strip | Integer | Strip the smallest prefix containing specified number of leading slashes from filenames | none | No
dir | String | The directory in which to run the patch command | none | No
haltonfailure | Boolean | Stop the build process if the patching process encounters an error. | false | No

### Example

    <patch
      patchfile="/path/to/patches/file.ext.patch"
      dir="/path/to/original"
    />

Apply "file.ext.path" to original file locataed in "/path/to/original" folder.

## PDOSQLExecTask

The PDOSQLExecTask executes SQL statements using PDO.

### Examples

    <pdosqlexec url="pgsql:host=localhost dbname=test">
      <fileset dir="sqlfiles">
    	  <include name="*.sql"/>
    	  </fileset>
    </pdosqlexec>

    <pdosqlexec url="mysql:host=localhost;dbname=test" userid="username" password="password">
      <transaction src="path/to/sqlfile.sql"/>
      <formatter type="plain" outfile="path/to/output.txt"/>
      </pdosqlexec>

Note: because of backwards compatiblity, the PDOSQLExecTask can also be called using the 'pdo' statement.

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

- transaction

  Wrapper for a single transaction. Transactions allow several files or blocks of statements to be executed using the same PDO connection and commit operation in between.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  tsrcfile | String | File with statements to be run as one transaction | n/a | No

- fileset

  Files containing SQL statements.

- filelist

  Files containing SQL statements.

- formatter

  The results of any queries that are executed can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. The path to the output file file can be specified by the outfile attribute; there is a default filename that will be returned by the formatter if no output file is specified.

  There are three predefined formatters - one prints the query results in XML format, the other emits plain text. Custom formatters that extend phing.tasks.pdo.PDOResultFormatter can be specified.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | Use a predefined formatter (either xml or plain). | n/a | One of these attributes is required.
  classname | String | Name of a custom formatter class (must extend phing.tasks.ext.pdo.PDOResultFormatter). | n/a
  usefile | Boolean | Boolean that determines whether output should be sent to a file. | true | No
  outfile | File | Path to file in which to store result. | Depends on formatter | No
  showheaders | Boolean | (only applies to plain formatter) Whether to show column headers. | false | No
  coldelim | String | (only applies to plain formatter) The column delimiter. | , | No
  rowdelim | String | (only applies to plain formatter) The row delimiter. | \n | No
  encoding | String | (only applies to XML formatter) The xml document encoding. | (PHP default) | No
  formatoutput | Boolean | (only applies to XML formatter) Whether to format XML output. | true | No

  ### Examples

      <pdo url="pgsql:host=localhost dbname=test">
        <fileset dir="sqlfiles">
      	  <include name="*.sql"/>
        </fileset>

        <!-- xml formatter -->
        <formatter type="xml" output="output.xml"/>

        <!-- custom formatter -->
        <formatter classname="path.to.CustomFormatterClass">
          <param name="someClassAttrib" value="some-value"/>
        </formatter>

        <!-- No output file + usefile=false means it goes to phing log -->
        <formatter type="plain" usefile="false" />
      </pdo>

## 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 dir=".">
      <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

  The <mapping> tag represents a complex data type. You can use nested <mapping> (and nested <element> with <element> tags) to represent the full complexity of the structure. Bear in mind that what you are creating will be mapped to an associative array that will be passed in via `PEAR_PackageFileMaintainer::setOptions()`.

      <mapping name="option_name">
          <element key="key_name" value="key_val"/>
          <element key="key_name" value="key_val"/>
      </mapping>

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

- fileset

- option

  Available options:

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  summary | String |  | n/a | Yes
  description | String |  | n/a | Yes
  license | String |  | n/a | Yes
  channel | String | Channel name (not alias!). Must be registered (`pear channel-discover channel`) on the machine, where the build will be. | n/a | Yes
  apiversion | String |  | n/a | Yes
  releaseversion | String |  | n/a | Yes
  releasestability | String | One from: snapshot, devel, alpha, beta or stable. | n/a | Yes
  apistability | String | One from: devel, alpha, beta or stable. | n/a | Yes
  note | String |  | n/a | Yes
  packagetype | String |  | n/a | Yes
  phpdep | String |  | n/a | Yes
  pearinstallerdep | String |  | n/a | Yes

- mapping

  The <mapping> tag represents a complex data type. You can use nested <mapping> (and nested <element> with <element> tags) to represent the full complexity of the structure. Bear in mind that what you are creating will be mapped to an associative array that will be passed in via `PEAR_PackageFileMaintainer::setOptions()`.

      <mapping name="option_name">
          <element key="key_name" value="key_val"/>
          <element key="key_name" value="key_val"/>
      </mapping>

  Available mappings and they structures:

  - deps (optional)

    Name | Type | Description | Default | Required
    --- | --- | --- | --- | ---
    channel | String | Channel name, from package is. | n/a | Yes
    name | String | Package name in channel. | n/a | Yes
    version | String | Minimal version. | n/a | Yes
    max | String | Maximum version. | Same as version. | No
    recommended | String | Recommended version. | Same as version. | No

  - maintainers (required at least one)

    Name | Type | Description | Default | Required
    --- | --- | --- | --- | ---
    handle | String | User identifier in channel. | n/a | Yes
    name | String | Real name. | n/a | Yes
    email | String |  | n/a | Yes
    role | String | One from: lead, developer, contributor or helper. | n/a | Yes

## PharPackageTask

Phar packages generating with Phing. This task require PECL's Phar extension to be installed on your system. Phar is built-in in PHP from 5.3 version.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
basedir | String | Base directory, which will be deleted from each included file (from path). Paths with deleted basedir part are local paths in package. | n/a | Yes
destfile | String | Destination (output) file. Will be recreated, if exists! | n/a | Yes
compression | String | Compression type (gzip, bzip2, none) to apply to the packed files. | none | No
webstub | String | Relative path within the phar package to run, if accessed through a web browser. | n/a | No
clistub | String | Relative path within the phar package to run, if accessed on the command line. | n/a | No
stub | String | A path to a php file that contains a custom stub | n/a | No
alias | String | An alias to assign to the phar package | n/a | No
signature | String | Signature algorithm (md5, sha1, sha256, sha512), used for this package. | sha1 | No

### Supported Nested Tags

- fileset
- metadata

### Examples

Sample build command:

    <pharpackage
      destfile="./build/package.phar"
      basedir="./">
      <fileset dir="./classes">
        <include name="**/**" />
      </fileset>
      <metadata>
        <element name="version" value="1.0" />
        <element name="authors">
          <element name="John Doe">
            <element name="e-mail" value="john@example.com" />
          </element>
        </element>
      </metadata>
    </pharpackage>

## PhkPackageTask

This task runs PHK_Creator.phk to build PHK-package. Learn more about build process in PHK Builder's Guide.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
phkcreatorpath | String | Path to PHK_Creator.phk. | n/a | Yes
inputdirectory | String | Path to directory, that will be packed. | n/a | Yes
outputfile | String | Output PHK-file. Directory, where file will be stored, must exist! | n/a | Yes
compress | String | Compression type (gzip, bzip2, none) to apply to the packed files. | none | No
strip | Boolean | When true, PHP source file(s) are stripped (filtered through php_strip_whitespace()) before being stored into the archive. | false | No
name | String | The package's name (Information only). | n/a | No
webrunscript | String | The script to run in web direct access mode. Subfile path. | n/a | No
crccheck | Boolean | If true, a CRC check will be forced every time the package is mounted. | false | No

### Supported Nested Tags

- webaccess

  Collection of path tags (see example below), that will be visible outside package in web mode.

### Examples

Sample build command:

    <phkpackage
        phkcreatorpath="/path/to/PHK_Creator.phk"
        inputdirectory="src"
        outputfile="build/sample-project.phk"
        compress="gzip"
        strip="true"
        name="Sample Project"
        webrunscript="index.php">
        <webaccess>
            <path>/</path>
        </webaccess>
    </phkpackage>

## PhpCodeSnifferTask

This task runs PHP_CodeSniffer to detect violations of a defined set of coding standards.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
standard | String | The name of the standard to check for. | Generic | No
format | String | The output format. The default format is specified in the task itself. Additionally all report formats of PHP_CodeSniffer can be choosen (ex. checkstyle, full, summary, ...). | default | No Ignored if nested formatter elements are supplied.
showSniffs | Boolean | Print the list of used sniffs. | false | No
showWarnings | Boolean | Print warnings. | true | No
showSources | Boolean | Flag that determines whether to show sources or not. | true | No
docGenerator | String | The name of the doc generator (HTML, Text). | n/a | No
docFile | String | Path to write output file to. If not set documentation will be written to STDOUT when docGenerator is set. | n/a | No
file | String | The file or folder to check (usually the nested tag fileset is used instead). | false | Either this attribute or the nested tag fileset is required.
sniffs | String | The list of allowed sniffs (separated by space, comma or semicolon). The sniffs must be part of the choosen standard. | n/a | No
verbosity | Integer | The verbosity level of CodeSniffer where level 1 prints progress information and level 2 prints developer debug information. | 0 | No
tabWidth | Integer | Replaces tabs with the given number of spaces. If zero no replacing is done. | 0 | No
reportWidth | Integer | The max. width for the report. | 80 | No
allowedFileExtensions | String | The allowed file extensions (separated by space, comma or semicolon) when a directory is specified in the file attribute. | php | No
ignorePatterns | String | The patterns to ignore files and folders (separated by space, comma or semicolon) when a directory is specified in the file attribute. | n/a | No
noSubdirectories | Boolean | Do not recurse into subdirectories when a directory is specified in the file attribute. | false | No
haltonerror | Boolean | Stop the build process if errors occurred during during the run. | false | No
haltonwarning | Boolean | Stop the build process if warnings occurred during the run. | false | No

### Supported Nested Tags

- fileset

  Either this nested tag or the attribute file is required.

- config

  The configuration parameters which are usually loaded from the CodeSniffer.conf can be set.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  name | String | Name of the configuration parameter. | n/a | Yes
  value | String | Value of the configuration parameter. | n/a | Yes

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

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | The output format. Accepts the the same values as the format attribute (default, xml, checkstyle, csv, report, summary & doc). | n/a | Yes
  usefile | Boolean | Boolean that determines whether output should be sent to a file. | true | No
  outfile | String | Path to write output file to. | n/a | Yes, if usefile is true.

### Examples

Checks all files in the directory file matching the allowed file extension with the PEAR standard and prints the summary report without warnings.

    <phpcodesniffer
      standard="PEAR"
      format="summary"
      file="/path/to/source-files"
      allowedFileExtensions="php php5 inc"/>

Checks all matching files in the fileset with the Zend standard, sets the zend_ca_path configuration which may be required by one of the sniffs, prints a list of used sniffs and prints the default report with warnings and the checkstyle report to /path/to/checkstyle.xml.

    <phpcodesniffer
      standard="Zend"
      showSniffs="true"
      showWarnings="true">
      <fileset dir="/path/to/source-files">
        <include name="**/*.php"/>
      </fileset>
      <config name="zend_ca_path" value="/path/to/ZendStudio/bin/ZendCodeAnalyzer"/>
      <formatter type="default" usefile="false"/>
      <formatter type="checkstyle" outfile="/path/to/checkstyle.xml"/>
    </phpcodesniffer>

Checks all files in the directory file with the PEAR standard and prints the checkstyle report without warnings. It also generates the documentation for the selected coding standard and writes it to the given file.

    <phpcodesniffer
      standard="PEAR"
      file="/path/to/source-files"
      docGenerator="HTML"
      docFile="/path/to/doc.html">
      <formatter type="checkstyle" outfile="/path/to/checkstyle.xml"/>
    </phpcodesniffer>

## PHPCPDTask

This task runs phpcpd, a Copy/Paste Detector (CPD) for PHP Code. You need an installed version of this software to use this task.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | Path to source file or path | n/a | No
minTokens | Integer | Sets the minimum number of identical tokens (default: 70) | 70 | No
minLines | Integer | Sets the minimum number of identical lines (default: 5) | 5 | No
format | String | The format for the report when no nested formatter is used. | default | No

### Supported Nested Tags

- fileset

  This nested tag is required when the file attribute is not set.

- formatter

  The results of the copy/paste scan can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | The output format. Accepts the the same values as the format attribute (default, pmd). | n/a | Yes
  useFile | Boolean | Flag that determines whether output should be sent to a file or not. | true | No
  outfile | String | Path to write output file to. | n/a | Yes

### Examples

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

Checking for copy/paste code in one particular source file. Sending Default-Report to STDOUT.

     <phpcpd file="path/to/source">
       <formatter type="pmd" outfile="reports/pmd-cpd.xml"/>
     </phpcpd>

Checking for copy/paste code in files of the given path.

     <phpcpd>
       <fileset dir="${builddir}" id="filestocpd">
         <include name="apps/**/*.php" />
         <include name="lib/de/**/*.php" />
         <include name="lib/task/**/*.php" />
         <include name="lib/services/**/*.php" />
         <include name="lib/form/**/*.php" />
         <include name="lib/model/**/*.php" />
       </fileset>
       <formatter type="pmd" outfile="reports/pmd-cpd.xml"/>
     </phpcpd>

## PHPMDTask

This task runs phpmd, a Project Mess Detector (PMD) for PHP Code. You need an installed version of this software to use this task.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | Path to source file or path | n/a | No
rulesets | String | Sets the rulesets used for analyzing the source code | codesize,unusedcode | No
minimumPriority | Integer | The minimum priority for rules to load. | 5 | No
allowedFileExtensions | String | Comma-separated list of valid file extensions (without dot) for analyzed files. | php | No
ignorePatterns | String | Comma-separated list of directory patterns to ignore. | .git,.svn,CVS,.bzr,.hg | No
format | String | The format for the report when no nested formatter is used. | text | No

### Supported Nested Tags

- fileset

  This nested tag is required when the file attribute is not set.

- formatter

  The results of the analysis can be printed in different formats. Output will always be sent to STDOUT, unless you set the usefile attribute to true and set an filename in the outfile attribute.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | The output format. Accepts the the same values as the format attribute (xml, html, text). | n/a | Yes
  usefile | Boolean | Boolean that determines whether output should be sent to a file. | true | No
  outfile | String | Path to write output file to. | n/a | Yes

### Examples

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

Checking syntax of one particular source file. Sending Text-Report to STDOUT.

     <phpmd file="path/to/source">
       <formatter type="html" outfile="reports/pmd.html"/>
     </phpmd>

Checking syntax of source files in the given path.

     <phpmd>
       <fileset dir="${builddir}">
         <include name="apps/**/*.php" />
         <include name="lib/de/**/*.php" />
       </fileset>
       <formatter type="xml" outfile="reports/pmd.xml"/>
     </phpmd>

Checking syntax of source files in the fileset pathes.

## PhpDependTask

This task runs PHP_Depend, a software analyzer and metric tool for PHP Code. You need an installed version of this software to use this task.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | Path to source file or path | n/a | No
configFile | String | Path to PHP_Depend configuration file | n/a | No
allowedFileExtensions | String | Comma-separated list of valid file extensions (without dot) for analyzed files. | php,php5 | No
excludeDirectories | String | Comma-separated list of directory patterns to ignore. | .git,.svn,CVS | No
excludePackages | String | Comma-separated list of packages to ignore. | n/a | No
withoutAnnotations | Boolean | Should the parse ignore doc comment annotations? | false | No
supportBadDocumentation | Boolean | Should PHP_Depend treat +global as a regular project package? | false | No
optimization | String | Which optimization strategy should be choosen (best, none) ? | best | No
debug | Boolean | Enable debug output? | false | No
haltonerror | Boolean | Stop the build process if errors occurred during the run. | false | No

### Supported Nested Tags

- fileset

  This nested tag is required when the file attribute is not set.

- logger

  The results of the analysis can be parsed by differed loggers. At least one logger is required. Output will always be sent to a file.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | The name of the logger. Valid loggers are: jdepend-chart, jdepend-xml, overview-pyramid, phpunit-xml and summary-xml. | n/a | Yes
  outfile | String | Path to write output file to. | n/a | Yes

- analyzer

  Some additional analyzers can be added to the runner.

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | The name of the analyzer. Valid analyzers are: coderank-mode. | n/a | Yes
  value | String | The value for the analyzer. | n/a | Yes

### Examples

     <phpdepend file="path/to/source">
       <logger type="phpunit-xml" outfile="reports/metrics.xml"/>
     </phpdepend>

Running code analysis for source files in the given path.

     <phpdepend>
       <fileset dir="${builddir}">
         <include name="apps/**/*.php" />
         <include name="lib/de/**/*.php" />
       </fileset>
       <logger type="jdepend-xml" outfile="reports/jdepend.xml"/>
       <analyzer type="coderank-mode" value="method"/>
     </phpdepend>

Running code analysis for source files in the fileset pathes with CodeRank strategy method.

## 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
templatebase | String | Set base dirctory of all templates for this parse. | n/a | No
undocumentedelements | Boolean | Control whether or not warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented. | false | No
customtags | Boolean | Custom tags, will be recognized and put in tags[] instead of unknowntags[]. | false | No
ignore | String | List of files to ignore, separated by ','. | n/a | No

### Supported Nested Tags

- fileset - Files that should be included for parsing
- projdocfileset - Files that should be treated as README/INSTALL/CHANGELOG files

### Examples

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

## PhpDocumentorExternalTask

This is the same as the PhpDocumentorTask but uses the command line application. Use this as a fallback in case you're running into troubles when using the phpDocumentor-library with the PhpDocumentorTask directly, e.g. when you're using Smarty and have Smarty in your library path too.

This task supports everything the PhpDocumentorTask supports, differences are documented below.

### Additional attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
programpath | String | Path to the phpdoc executable (relative or absolute). | n/a | No
sourcepath | String | A directory to scan for parsable files. Supports multiple directories separated with a comma. | n/a | Yes, if no `<fileset>` is given

### Unsupported attributes

Name | Description
--- | ---
configdir | Currently not supported. The attribute will be ignored and a warning messag will be generated. The build continues (to ease when changing an existing phpdoc task) however this may have unexpected side effects.

### Examples

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

## 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 encounters an error. | false | No
errorproperty | String | The name of a property that will be set to contain the error string (if any). | n/a | No
interpreter | string | Path to alternative PHP interpreter | Defaults to the `${php.command}` property which is the interpreter used to execute phing itself. | No
cachefile | String | If set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely change | none | No
level | String | Control the level at which phplint reports status messages. One of error, warning, info, verbose, debug. | info | No
tofile | String | File to write list of 'bad files' to. | n/a | No
deprecatedAsError | Boolean | Whether to treat deprecated warnings (introduced in PHP 5.3) as errors. | n/a | false

### Supported Nested Tags

- fileset

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

## PHPUnitTask

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

NB: the identifiers phpunit2 (PHPUnit2Task) and phpunit3 (PHPUnit3Task) have been deprecated!

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
printsummary | Boolean | Print one-line statistics for each testcase. | false | No
bootstrap | string | The name of a bootstrap file that is run before executing the tests. | none | No
codecoverage | Boolean | Gather code coverage information while running tests (requires Xdebug). | 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
haltonincomplete | Boolean | Stop the build process if any incomplete tests are encountered. | false | No
haltonskipped | Boolean | Stop the build process if any skipped tests are encountered. | false | No
failureproperty | String | Name of property to set (to true) on failure. | n/a | No
errorproperty | String | Name of property to set (to true) on error. | n/a | No
incompleteproperty | String | Name of property to set (to true) on incomplete tests. | n/a | No
skippedproperty | String | Name of property to set (to true) on skipped tests. | n/a | No
usecustomerrorhandler | Boolean | Use a custom Phing/PHPUnit error handler to process PHP errors. | true | 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.phpunit.formatter.PHPUnitResultFormatter can be specified.

  p>

  ### Attributes

  Name | Type | Description | Default | Required
  --- | --- | --- | --- | ---
  type | String | Use a predefined formatter (either xml, plain, clover, 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

- 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 lists of classes that are (in)directly defined by each PHP file.

  ### Attributes

  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
  name | String | The name that is used to create a testsuite from this batchtest. | Phing Batchtest | No

  ### Supported Nested Tags

  - fileset

### Examples

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

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

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

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

    <phpunit bootstrap="src/autoload.php">
      <formatter type="plain" usefile="false"/>
      <batchtest>
        <fileset dir="tests">
          <include name="**/*Test*.php"/>
        </fileset>
      </batchtest>
    </phpunit>

Runs all matching testcases in the directory tests, writing plain text results to the console. Additionally, before executing the tests, the bootstrap file src/autoload.php is loaded.

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.

## PHPUnitReport

This task transforms PHPUnit xml reports to HTML using XSLT.

NB: the identifiers phpunit2report (PHPUnit2Report) and phpunit3report (PHPUnit3Report)have been deprecated!

### 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 phpunit-frames.xsl. noframes format: the stylesheet must be named phpunit-noframes.xsl. | n/a | Yes
todir | String | The directory where the files resulting from the transformation should be written to. |  | Yes

### Examples

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

## ScpTask

The ScpTask copies files to and from a remote host using scp. This task requires the PHP SSH2 extension to function.

### Examples

    <scp username="john" password="smith"
    host="webserver" fetch="true"
    todir="/home/john/backup"
    file="/www/htdocs/test.html" />

Fetches a single file from the remote server.

    <scp username="john" password="smith"
    host="webserver"
    todir="/www/htdocs/"
    file="/home/john/dev/test.html" />

Copies a single file to the remote server.

    <scp username="john" password="smith"
    host="webserver" todir="/www/htdocs/project/">
        <fileset dir="test">
            <include name="*.html" />
        </fileset>
    </scp>

Copies multiple files to the remote server.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
host | String | Remote host | none | Yes
port | Integer | Remote port | 22 | No
username | String | Username to use for the connection | none | Yes
password | String | Password to use for the connection | none | No
pubkeyfile | String | Public key file to use for the connection | none | No
privkeyfile | String | Private key file to use for the connection | none | No
privkeyfilepassphrase | String | Private key file passphrase to use for the connection | none | No
autocreate | Boolean | Whether to autocreate remote directories | true | No
todir | String | Directory to put file(s) in | none | No
file | String | Filename to use | none | No
fetch | Boolean | Whether to fetch (instead of copy to) the file | false | No

### Supported Nested Tags

- fileset

## SshTask

The ScpTask executes commands on a remote host using ssh.. This task requires the PHP SSH2 extension to function.

### Examples

    <ssh username="john" password="smith"
    host="webserver" command="ls" />

Executes a single command on the remote server.

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
host | String | Remote host | none | Yes
port | Integer | Remote port | 22 | No
username | String | Username to use for the connection | none | Yes
password | String | Password to use for the connection | none | No
pubkeyfile | String | Public key file to use for the connection | none | No
privkeyfile | String | Private key file to use for the connection | none | No
privkeyfilepassphrase | String | Private key file passphrase to use for the connection | none | No
command | String | Command to execute on the remote server | none | Yes

## SimpleTestTask

This task runs testcases using the SimpleTest framework.

### 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
failureproperty | String | Name of property to set (to true) on failure. | n/a | No
errorproperty | String | Name of property to set (to true) on error. | n/a | No
debug | Boolean | Switch debugging on/off | 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.PHPUnitResultFormatter 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 summary). | 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

- fileset

### Examples

    <simpletest>
      <formatter type="plain"/>
      <fileset dir="tests">
        <include name="**/*Test*.php"/>
        <exclude name="**/Abstract*.php"/>
      </fileset>
    </simpletest>

Runs all matching testcases in the directory tests, writing plain text results to the console.

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

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

## 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 | Boolean | Connection credentials will not be cached | False | No
todir | String | Path to export to | none | Yes
recursive | Boolean | Recursive behavior | true | No
ignoreexternals | Boolean | Ignore externals definitions | false | No

## SvnCommitTask

The SvnCommitTask commits a local working copy to a SVN repository and sets the specified property ( default svn.committedrevision) to the revision number of the committed revision.

### Examples

    <svncommit
        svnpath="/usr/bin/svn"
        username="anony"
        password="anony"
        nocache="true"
        workingcopy="/home/joe/dev/project"
        message="Updated documentation, fixed typos" />

The most basic usage only needs the working copy and the commit message as in

    <svncommit
        workingcopy="/home/joe/dev/project"
        message="Updated documentation, fixed typos" />
    <echo message="Committed revision: ${svn.committedrevision}"/>

### 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 | Boolean | Connection credentials will not be cached | false | No
recursive | Boolean | Recurse into all subdirectories | false | No
workingcopy | String | Working copy | none | Yes
message | String | The commit message | none | Yes
ignoreexternals | Boolean | Ignore externals definitions | false | No
propertyname | String | Name of property to set to the last committed revision number | svn.committedrevision | No

## SvnCopyTask

The SvnCopyTask duplicates something in a working copy or repository, remembering history.

### Examples

    <svncopy
       svnpath="/usr/bin/svn"
       username="anony"
       password="anony"
       force="true"
       nocache="true"
       repositoryurl="svn://localhost/project/trunk/"
       todir="svn://localhost/project/tags/0.1"/>

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
message | String | Log message | n/a | No
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 | Boolean | Force overwrite files if they already exist | False | No
nocache | Boolean | Connection credentials will not be cached | False | No
todir | String | Path to export to | none | Yes
recursive | Boolean | Recursive behavior | True | No
ignoreexternals | Boolean | Ignore externals definitions | False | No

## 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
--- | --- | --- | --- | ---
revision | String | Revision to use in export | HEAD | No
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 | Boolean | Force overwrite files if they already exist | False | No
nocache | Boolean | Connection credentials will not be cached | False | No
todir | String | Path to export to | none | Yes
recursive | Boolean | Recursive behavior | True | No
ignoreexternals | Boolean | Ignore externals definitions | False | No

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

    <svnlastrevision
       svnpath="C:/Subversion/bin/svn.exe"
       repositoryurl="http://svn.phing.info/"
       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, or repositoryurl
repositoryurl | String | URL of remote repository | none | Yes, or workingcopy
propertyname | String | Name of property to use | svn.lastrevision | No
forceCompatible | Boolean | Sets whether to force compatibility with older SVN versions (< 1.2) | false | 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 | Boolean | Connection credentials will not be cached | False | No
todir | String | Path to export to | none | Yes
recursive | Boolean | Recursive behavior | Frue | No
ignoreexternals | Boolean | Ignore externals definitions | False | 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 | none | 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
includeemptydirs | Boolean | If set to true, also empty directories are copied. | true | No
longfile | String | How to handle long files, those with a path > 100 chars. Allowable values are: truncate - paths are truncated to the maximum length fail - paths greater than the maximim cause a build exception warn - paths greater than the maximum cause a warning and GNU is used gnu - GNU extensions are used for any paths greater than the maximum omit - paths greater than the maximum are omitted from the archive | warn | No
prefix | String | File path prefix to use when adding files to archive | 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

- fileset

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

- fileset

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

- fileset

## VersionTask

The VersionTask increments a three-part version number from a given file and writes it back to the file. The resulting version number is also published under supplied property.

The version number in the text file is expected in the format of Major.Minor.Bugfix (e.g. 1.3.2).

### Examples

    <version releasetype="Major" file="version.txt" property="version.number"/>

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
releasetype | String | Specifies desired version release (Major, Minor or Bugfix) | n/a | Yes
file | String | File containing three-part version number to increment | n/a | Yes
property | String | Property which contains the resulting version number | n/a | Yes

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

- fileset

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

## XmlPropertyTask

Loads property values from a well-formed xml file. There are no other restrictions than "well-formed".

### Attributes

Name | Type | Description | Default | Required
--- | --- | --- | --- | ---
file | String | The XML file to parse. | n/a | Yes
prefix | String | The prefix to prepend to each property | n/a | No
keepRoot | Boolean | Keep the xml root tag as the first value in the property name. | true | No
collapseAttributes | Boolean | Treat attributes as nested elements. | false | No
delimiter | String | Delimiter for splitting multiple values. | , | No

### Example

Consider the following XML file:

    <root-tag myattr="true">
        <inner-tag someattr="val">Text</inner-tag>
        <a2><a3><a4>false</a4></a3></a2>
    </root-tag>

Used with the the following entry (default):

    <xmlproperty file="somefile.xml"/>

results in the following properties:

    root-tag(myattr)=true
    root-tag.inner-tag=Text
    root-tag.inner-tag(someattr)=val
    root-tag.a2.a3.a4=false

Used with the the following entry (collapseAttributes=true):

    <xmlproperty file="somefile.xml" collapseAttributes="true"/>

results in the following properties:

    root-tag.myattr=true
    root-tag.inner-tag=Text
    root-tag.inner-tag.someatt=val
    root-tag.a2.a3.a4=false

Used with the the following entry (keepRoot=false):

    <xmlproperty file="somefile.xml" keepRoot="false"/>

results in the following properties:

    inner-tag=Text
    inner-tag(someattr)=val
    a2.a3.a4=false

## 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
haltonwarning | Boolean | Stop the build process if warnings occurred during the run. | false | No

### Supported Nested Tags

- fileset

### Example

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

Analyze one PHP source file with all default warnings enabled.

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

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

NOTE: the analyze tag has been deprecated as of Phing 2.4.

## 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
prefix | String | File path prefix to use when adding files to zip | none | No

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

### Supported Nested Tags

- fileset