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.

ApiGenTask

This task runs ApiGen, a tool for creating professional API documentation from PHP source code, similar to discontinued phpDocumentor/phpDoc.

Attributes

Name Type Description Default Required
executable String ApiGen executable name. apigen No
config String Config file name. n/a Source and destination are required - either set explicitly or using a config file. Attribute values set explicitly have precedence over values from a config file.
source String List of source files or directories. n/a
destination String Destination directory. n/a
extensions String List of allowed file extensions. php No
exclude String List of masks (case sensitive) to exclude files or directories from processing. n/a No
skipdocpath String List of masks (case sensitive) to exclude elements from documentation generating. n/a No
skipdocprefix String Name prefix (case sensitive) to exclude elements from documentation generating. n/a No
charset String Character set of source files. auto No
main String Main project name prefix. n/a No
title String Title of generated documentation. n/a No
baseurl String Documentation base URL. n/a No
googlecseid String Google Custom Search ID. n/a No
googlecselabel String Google Custom Search label. n/a No
googleanalytics String Google Analytics tracking code. n/a No
templateconfig String Template config file name. n/a If not set the default template is used.
allowedhtml String List of HTML tags allowed in the documentation. b,i,a,ul,ol,li,p,br,var,samp,kbd,tt No
groups String How should elements be grouped in the menu. auto No
autocomplete String Element types for search input autocomplete. classes,constants,functions No
accesslevels String Element access levels. Documentation only for methods and properties with the given access level will be generated. public,protected No
internal Boolean Whether to generate documentation for elements marked as internal and internal documentation parts or not. No No
php Boolean Whether to generate documentation for PHP internal classes or not. Yes No
tree Boolean Whether to generate tree view of classes, interfaces, traits and exceptions or not. Yes No
deprecated Boolean Whether to generate documentation for deprecated elements or not. No No
todo Boolean Whether to generate documentation of tasks or not. No No
sourcecode Boolean Whether to generate highlighted source code files or not. Yes No
download Boolean Whether to generate a link to download documentation as a ZIP archive or not. No No
report String File name for checkstyle report of poorly documented elements. n/a No
wipeout Boolean Whether to wipe out the destination directory first or not. Yes No
quiet Boolean Whether to enable scaning and generating messages or not. No No
updatecheck Boolean Whether to check for ApiGen updates or not. No No
debug Boolean Whether to enable the debug mode or not. No No

Examples

<apigen
  source="classes"
  destination="api"
  exclude="*/tests/*"
  title="My Project API Documentation"
  deprecated="true"
  todo="true"/>

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>

ComposerTask

Executes Composer commands

Examples

Simple example

            <composer command="install"/>

Complex example

            <composer command="install">
                <arg value="--dev" />
            </composer>

Attributes

Name Type Description Default Required
command string The Composer command to execute n/a Yes
composer string The path to composer application composer.phar no
php string The path to the php executable php no

Supported Nested Tags

CoverageReportTask

The CoverageReportTask formats a coverage database into a framed HTML report using XSLT. The report can optionally make use of the Generic Syntax Highlighting library, GeSHi (See GeSHi Homepage) library to mark up source code. The path to the library (if not in the default path) can be specified as an attribute.

Attributes

Name Type Description Default Required
outfile String The location for the intermediate XML file. coverage.db Yes
classpath String Additional classpath to locate source referenced in the report n/a No
geshipath String Path to GeSHi highlighting library n/a No/Yes* If syntax highlighting si to be enabled
geshilanguagespath String Language to use with GeSHi n/a No

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.

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

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.

<coverage-threshold
    perProject="50"
    perClass="60"
    perMethod="70"/>
    <excludes>
        <file>**/*Processor.php</file>
        <class>Model_Filter_Windows</class>
        <method>Model_System::execute()</method>
    </excludes>

Validates the code coverage database (from CoverageSetupTask) against the specified thresholds and excludes the given file, class and method from threshold validation. The filename is relative to the project basedir. A Method can be named either "Model_System::execute()" or "Model_System::execute". The method name is considered only for the given class "Model_System".

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

<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

DocBloxTask

This task is now deprecated in favor of the PhpDocumentor2Task.

This task runs DocBlox, a PHP 5.3-compatible API documentation tool.

Attributes

Name Type Description Default Required
title String Title of the project. n/a No
destdir String Destination directory for output files. n/a Yes
template String Name of the DocBlox template to use. default No
quiet Boolean Suppress DocBlox chatter. true No

Supported Nested Tags

Examples

<docblox title="API Documentation"
  destdir="apidocs"
  template="new_black">
   <fileset dir="./classes">
      <include name="**/*.php" />
   </fileset>
</docblox>

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

FileSyncTask

Syncs files or directories using the rsync command. Syncing can be done on the same server or from/to a remote server.

Example

<sync sourcedir="/var/www/development/project1" destinationdir="/var/www/project1" />

<sync
sourcedir="/var/www/development/project1"
destinationdir="user@server:/var/www/project1"
dryrun="true"
itemizechanges="true"
verbose="true"
checksum="true" />

Attributes

Name Type Description Default Required
rsyncPath String Path to rsync command /usr/bin/rsync Yes
sourceDir String Source directory (with user&host for remote sources) n/a Yes
destinationDir String Destination directory (with user&host for remote destinations) n/a Yes
excludeFile String Excluded patterns file n/a No
backupDir String Creates a backup so users can rollback to an existing restore point n/a No
options String Any options that rsync supports, removes the default options -rpKz No
verbose Boolean This option increases the amount of information you are given during the transfer True No
dryRun Boolean This option makes rsync perform a trial run that doesn't make any changes False No
itemizeChanges Boolean This option requests a simple itemized list of the changes that are being made to each file, including attribute changes False No
checksum Boolean This option will cause rsync to skip files based on checksum, not mod-time & size False No
delete Boolean This option deletes files that don't exist on sender after transfer including 'force' and 'ignore-errors' False No
identityFile String Identity file for ssh authentication of a remote transfer n/a 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}" 
  passive="false"
  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 Integer 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
passive Boolean Open connection in passive mode false No
dirmode Boolean Permissions of the uploaded files, can either be 'inherit' or it can be a octal value without the leading zero. Setting the dirmode to 'inherit' will cause the uploaded files to have the same permissions as on the filesystem. false No
filemode Boolean This option does the same as dirmode, except it only affects regular files. false No
depends Boolean If depends is set to true, the task will only update files with a local modification timestamp that is newer than the corresponding timestamp on the server. false No
level String Control the level at which the task reports status messages. One of error, warning, info, verbose, debug. verbose No

Supported Nested Tags

GitInitTask

Create an empty git repository or reinitialize an existing one.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
bare Boolean Create bare repository. See --bare option of git-init. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- Initialize normal repository -->
<gitinit repository="${repo.dir.resolved}" />

<!-- Initialize bare repository -->
<gitinit bare="true" repository="${repo.dir.resolved}" />

GitCloneTask

Clone a repository into a new directory.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String The (possibly remote) repository to clone from. n/a Yes
targetPath String The name of a new directory to clone into. Cloning into an existing directory is only allowed if the directory is empty. n/a Yes
bare Boolean Create bare repository. See --bare option of git-clone. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- Clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- Clone bare repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}"
    bare="true" />

GitGcTask

Cleanup unnecessary files and optimize the local repository.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String The repository to cleanup. n/a Yes
aggressive Boolean This option will cause git gc to more aggressively optimize the repository at the expense of taking much more time. See --aggressive option of git-gc. false No
auto Boolean With this option, git gc checks whether any housekeeping is required; if not, it exits without performing any work. See --auto option of git-gc. false No
noprune Boolean Do not prune any loose objects. See --no-prune option of git-gc. false No
prune string Prune loose objects older than date. See --prune option of git-gc. 2.weeks.ago No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- Clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- Cleanup repository-->
<gitgc 
    repository="${repo.dir.resolved}" 
    aggressive="true"
    prune="1.week.ago" />

GitBranchTask

Create, move or delete repository branches. See official documentation (branch listing functionality is omitted in current implementation).

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
branchname String The name of the branch to create or delete. n/a Yes
newbranch String The new name for an existing branch. n/a Yes, if branch move invoked
startpoint String The new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this option is omitted, the current HEAD will be used instead. See <start-point> argument of git-branch. No
setupstream String If specified branch does not exist yet or if --force has been given, acts exactly like --track. Otherwise sets up configuration like --track would when creating the branch, except that where branch points to is not changed. See --set-upstream option of git-branch. No
track Boolean See --track option of git-branch. false No
notrack Boolean See --no-track option of git-branch. false No
force Boolean Reset <branchname> to <startpoint> if <branchname> exists already. Without -f git branch refuses to change an existing branch. false No
move Boolean Move/rename a branch and the corresponding reflog. false No
forcemove Boolean Move/rename a branch even if the new branch name already exists. false No
delete Boolean Delete a branch. The branch must be fully merged in its upstream branch, or in HEAD if no upstream was set with --track or --set-upstream. false No
forcedelete Boolean Delete a branch irrespective of its merged status. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- Initialize normal repository -->
<gitinit repository="${repo.dir.resolved}" />

<!-- Create branch "sample-branch" tracking current HEAD -->
<gitbranch
    repository="${repo.dir.resolved}" 
    branchname="sample-branch" />

<!-- 
Create branch "sample-branch" tracking origin/master 
Note that you can omit both startpoint and track attributes in this case
-->
<gitbranch
    repository="${repo.dir.resolved}" 
    branchname="sample-branch"
    startpoint="origin/master"
    track="true" />

<!-- Delete fully merged branch "sample-branch" -->
<gitbranch 
    repository="${repo.dir.resolved}" 
    branchname="sample-branch" 
    delete="true" />

<!-- Force delete even unmerged branch "sample-branch" -->
<gitbranch 
    repository="${repo.dir.resolved}" 
    branchname="sample-branch" 
    forcedelete="true" />

<!-- Renabe "branch1" to "branch2" -->
<gitbranch 
    repository="${repo.dir.resolved}" 
    branchname="branch1" 
    newbranch="branch2"
    move="true" />

GitFetchTask

Download objects and refs from another repository. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
source String The "remote" repository that is the source of a fetch or pull operation. See <repository> in git-fetch. origin No
refspec String See <refspec> in git-fetch. No
group String A name referring to a list of repositories as the value of remotes.<group> in the configuration file. See <group> in git-fetch. No
quiet Boolean Silence any internally used git commands. Progress is not reported to the standard error stream. See --quiet in git-fetch. false No
all Boolean Fetch all remotes. See --all in git-fetch. false No
keep Boolean Keep downloaded pack. See --keep in git-fetch. false No
prune Boolean After fetching, remove any remote tracking branches which no longer exist on the remote. See --prune in git-fetch. false No
tags Boolean See --tags in git-fetch. false No
notags Boolean See --no-tags in git-fetch. false No
force Boolean When git fetch is used with <rbranch>:<lbranch> refspec, it refuses to update the local branch <lbranch> unless the remote branch <rbranch> it fetches is a descendant of <lbranch>. This option overrides that check. See --force in git-fetch. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- Initialize normal repository -->
<gitinit repository="${repo.dir.resolved}" />

<!-- Fetch objects from all remotes -->
<gitfetch
    repository="${repo.dir.resolved}" all="true" />

<!-- Fetch from origin/master to "refspec-branch" local branch -->
<gitfetch 
    repository="${repo.dir.resolved}" 
    source="origin"
    refspec="master:refspec-branch" 
    quiet="true" />

GitCheckoutTask

Checkout a branch or paths to the working tree. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
branchname String Branch to checkout. See <branch> in git-checkout. origin No
startpoint String The name of a commit at which to start the new branch; Defaults to HEAD. See <start_point> in git-checkout. No
create Boolean Create a new branch named <branchname> and start it at <startpoint> false No
forcecreate Boolean Creates the branch <branchname> and start it at <startpoint>; if it already exists, then reset it to <startpoint>. This is equivalent to running "git branch" with "-f". false No
merge Boolean See --merge in git-checkout. false No
track Boolean See --track in git-checkout. false No
notrack Boolean See --no-track in git-checkout. false No
quiet Boolean Quiet, suppress feedback messages. See --quiet in git-checkout. false No
force Boolean When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes. See --force in git-checkout. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- create and switch to "mybranch" branch -->
<gitcheckout
    repository="${repo.dir.resolved}" 
    branchname="mybranch" quiet="true" create="true" />

<!-- get back to "master" branch -->
<gitcheckout
    repository="${repo.dir.resolved}" 
    branchname="master" quiet="true" />

<!-- create (force) already created branch -->
<gitcheckout
    repository="${repo.dir.resolved}" 
    branchname="mybranch" quiet="true" 
    forceCreate="true" />

GitMergeTask

Join two or more development histories together. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
remote String Space separated list of branches to merge into current HEAD. See <commit> in git-merge. n/a No
message String Commit message to be used for the merge commit (in case one is created). See <msg> in git-merge. n/a No
fastForwardCommit Boolean If set false (default), will not generate a merge commit if the merge resolved as a fast-forward, only update the branch pointer.
If set true, will generate a merge commit even if the merge resolved as a fast-forward. See --ff/--no-ff options in git-merge.
False No
strategy String Merge strategy. One of "resolve", "recursive", "octopus", "ours", or "subtree". See <strategy> in git-merge. n/a No
strategyOption String Pass merge strategy specific option through to the merge strategy. See <strategy-option> in git-merge. n/a No
commit Boolean See --commit in git-merge. false No
nocommit Boolean See --no-commit in git-merge. false No
quiet Boolean Quiet, suppress feedback messages. See --quiet in git-merge. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- create couple of test branches -->
<gitbranch
    repository="${repo.dir.resolved}" 
    branchname="merge-test-1" startpoint="origin/master" />
<gitbranch
    repository="${repo.dir.resolved}" 
    branchname="merge-test-2" startpoint="origin/master" />

<!-- Merge those branches back into master -->
<gitmerge
    repository="${repo.dir.resolved}" 
    remote="merge-test-1 merge-test-2" 
    message="merging repos" commit="true" />

GitPullTask

Fetch from and merge with another repository or a local branch. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
all Boolean Fetch all remotes false No
source String The "remote" repository that is the source of a fetch or pull operation. See <repository> in git-pull. origin Yes, if allRemotes set to false
refspec String See <refspec> in git-pull. n/a No
strategy String Merge strategy. One of "resolve", "recursive", "octopus", "ours", or "subtree". See <strategy> in git-pull. n/a No
strategyOption String Pass merge strategy specific option through to the merge strategy. See <strategy-option> in git-pull. n/a No
rebase Boolean See --rebase in git-pull. false No
norebase Boolean See --no-rebase in git-pull. false No
tags Boolean Enable tag references following. See --tags in git-pull. false No
notags Boolean Disable tag references following. See --no-tags in git-pull. false No
keepFiles Boolean See --keep in git-pull. false No
append Boolean See --append in git-pull. false No
quiet Boolean Quiet, suppress feedback messages. See --quiet in git-pull. false No
force Boolean Force update. See --force in git-pull. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- pull from all remotes -->
<gitpull
    repository="${repo.dir.resolved}" all="true" />

<!-- pull remote origin/foobranch and rebase when merging -->
<gitpull
    repository="${repo.dir.resolved}" 
    source="origin" refspec="foobranch" 
    strategy="recursive" keep="true"
    force="true" quiet="true" rebase="true" />

GitPushTask

Update remote refs along with associated objects. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
all Boolean Push all references false No
destination String The "remote" repository that is destination of a push operation. See <repository> in git-push. origin Yes, if allRemotes set to false
refspec String See <refspec> in git-push. n/a No
mirror Boolean See --mirror in git-push. false No
delete Boolean Delete "remote" reference. Same as prefixing the refspec with colon. See --delete in git-push. false No
tags Boolean Push all references under refs/tags. See --tags in git-push. false No
quiet Boolean Quiet, suppress feedback messages. See --quiet in git-push. false No
force Boolean Force update. See --force in git-push. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<!-- push branch "master" into "foobranch" on "origin" remote -->
<gitpush
    repository="${repo.dir.resolved}" 
    refspec="master:foobranch" tags="true" />

<!-- create new branch "newbranch" on "origin" remote -->
<gitpush
    repository="${repo.dir.resolved}" 
    refspec="master:newbranch" quiet="true" />

<!-- delete "newbranch" branch from "origin" remote -->
<gitpush
    repository="${repo.dir.resolved}" 
    delete="true"
    refspec="newbranch" quiet="true" />

GitTagTask

Create, list, delete or verify a tag object signed with GPG. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
message String Use given tag message. See -m of git-tag n/a No
name String Tag name n/a Yes
commit String <commit> argument to git-tag n/a No
object String <object> argument to git-tag n/a No
pattern String <pattern> argument to git-tag n/a No
outputProperty String Property name to set with output value from git-tag n/a No
file String Take tag message from given file. See -F of git-tag n/a No
annotate Boolean Make unsigned, annotated tag object. See -a of git-tag false No
force Boolean Replace existing tag with given name. See -f of git-tag false No
delete Boolean Delete existing tags with given names. See -d of git-tag false No
list Boolean List tags with names matching given pattern. See -l of git-tag false No
num Integer Specifies how many lines from the annotation, if any, are printed when using -l. See -n of git-tag n/a No
contains String Only list tags containing specified commit. See --contains of git-tag n/a No
sign Boolean Make GPG-signed tag. See -s of git-tag false No
keySign String Make GPG-signed tag, using given key. See -u of git-tag of git-tag n/a No
verify Boolean Verify GPG signature of given tag names. See -v of git-tag false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<gittag repository="${repo.dir.resolved}" name="ver1.0" />
<!-- Force duplicate tag creation -->
<gittag 
    repository="${repo.dir.resolved}" 
    name="ver1.0" force="true"/>
<!-- Create tag with annotation and message -->
<gittag 
    repository="${repo.dir.resolved}" 
    name="ver1.0"
    annotate="true" message="Version 1.0 tag"/>
<!-- Delete tag -->
<gittag 
    repository="${repo.dir.resolved}"
        name="ver2.0" delete="true" />
<!-- List tags matching to pattern "marked" into "tags" variable -->
<gittag repository="${repo.dir.resolved}" 
    list="true"
    outputProperty="tags" 
    pattern="marked" />

GitLogTask

Show commit logs. See official documentation.

Attributes

Name Type Description Default Required
gitPath String Path to Git binary /usr/bin/git No
repository String Path to Git repository n/a Yes
paths String <path> arguments to git-log. Accepts one or more paths delimited by PATH_SEPARATOR n/a No
outputProperty String Property name to set with output value from git-log n/a No
format String Commit format. See --format of git-log. Can be one of oneline, short, medium, full, fuller, email, raw and format:<string> medium No
date String Date format. See --date of git-log. n/a No
since String <since> argument to git-log. n/a No
until String <until> argument to git-log. HEAD No
stat String Generate a diffstat. See --stat of git-log n/a No
nameStatus Boolean Names + status of changed files. See --name-status of git-log. false No
maxCount Integer Number of commits to show. See -<n>|-n|--max-count of git-log. n/a No
noMerges boolean Don't show commits with more than one parent. See --no-merges of git-log. false No

Example

<property name="repo.dir" value="./relative/path/to/repo" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />

<!-- clone repository -->
<gitclone 
    repository="git://github.com/path/to/repo/repo.git"
    targetPath="${repo.dir.resolved}" />

<gitlog 
    paths="${repo.dir.resolved}"
    format="oneline"
    maxCount="2"
    stat="true"
    noMerges="false"
    since="Sun Jan 23 23:55:42 2011 +0300"
    until="Mon Jan 24 09:59:33 2011 +0300"
    outputProperty="logs" 
    repository="${repo.dir.resolved}" />

GrowlNotifyTask

When you have a long process and want to be notified when it is finished, without to stay focused on the console windows. Then use the GrowlNotify task.

This task requires the PEAR Net_Growl package installed (version 2.6.0).

Features

Attributes

Name Type Description Default Required
name String Name of application to be register Growl for Phing No
sticky Boolean Indicates if the notification should be sticky on desktop false No
message String Text of notification. Use \n to specify a line break n/a Yes
title String Title of notification GrowlNotify No
notification String The notification name/type General Notification No
appicon String

The icon of the application being registered.

Must be a valid file type (png, jpg, gif, ico). Can be any of the following:

  • absolute url (http://domain/image.png)
  • absolute file path (c:\temp\image.png)
  • relative file path (.\folder\image.png)
n/a No
host String The host address where to send the notification 127.0.0.1 No
password String The password required to send notifications over network n/a No
priority String

The notification priority

Valid values are :

  • low
  • moderate
  • normal
  • high
  • emergency
normal No
protocol String

The protocol used to send the notification.

May be either gntp or udp.

gntp No
icon String

The icon to show for the notification.

Must be a valid file type (png, jpg, gif, ico). Can be any of the following:

  • absolute url (http://domain/image.png)
  • absolute file path (c:\temp\image.png)
  • relative file path (.\folder\image.png)
embeded growl icon v2 No

Examples

Send a single notification on a remote host

Both sender and Growl client (Mac or Windows) should share the same password.

<?xml version="1.0" encoding="UTF-8"?>
<project name="phing-GrowlNotifyTask" basedir="." default="notification">

    <taskdef name="growlnotify" classname="phing.tasks.ext.GrowlNotifyTask" />

    <target name="notification"
        description="display a single message with growl gntp over network"
    >
        <growlnotify message="Deployment of project LAMBDA is finished."
            host="192.168.1.2"
            password="seCretPa$$word"
        />
    </target>

</project>

Send a single notification with UDP protocol

When you don't have a Macintosh, OS compatible with Growl GNTP, you should use the basic UDP protocol.

<?xml version="1.0" encoding="UTF-8"?>
<project name="phing-GrowlNotifyTask" basedir="." default="notification">

    <taskdef name="growlnotify" classname="phing.tasks.ext.GrowlNotifyTask" />

    <target name="notification"
        description="display a single message with growl udp over network"
    >
        <growlnotify message="Notify my MAC that does not accept GNTP."
            host="192.168.1.2"
            password="seCretPa$$word"
            protocol="udp"
        />
    </target>

</project>

Send an important notification

If you want to send a notification that is so important that you don't want to missed it, even if you are away from your computer. Use the sticky attribute.

<?xml version="1.0" encoding="UTF-8"?>
<project name="phing-GrowlNotifyTask" basedir="." default="notification">

    <taskdef name="growlnotify" classname="phing.tasks.ext.GrowlNotifyTask" />

    <target name="notification"
        description="display a sticky message on desktop"
    >
        <growlnotify message="Project LAMDBA, unit tests FAILED."
            priority="high"
            sticky="true"
        />
    </target>

</project>

Use your icons to identify an application

You may customize the Growl notification system, with different icons and more.

<?xml version="1.0" encoding="UTF-8"?>
<project name="phing-GrowlNotifyTask" basedir="." default="notification">

    <taskdef name="growlnotify" classname="phing.tasks.ext.GrowlNotifyTask" />

    <target name="notification"
        description="display a custom icon message"
    >
        <growlnotify message="Have a look on my beautiful message!"
            name="phing Notifier"
            title="phing notification"
            priority="low"
            sticky="false"
            appicon="../images/my_icon.png"
        />
    </target>

</project>

HttpGetTask

This task will download a file through HTTP GET and save it to a specified directory. 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
dir String The directory to save the file n/a Yes
filename String The filename for the downloaded file The filename part of the URL No
followRedirects Boolean Whether to follow HTTP redirects false No
sslVerifyPeer Boolean Whether to verify SSL certificates true No

Example

 <httpget url="http://buildserver.com/builds/latest.stable.tar.bz2" dir="/usr/local/lib"/>

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

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 Whether to disable support for runtime initialization of the ionCube Loader false No
noshortopentags Boolean Whether 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
ignoredeprecatedwarnings Boolean Whether to ignore deprecated warnings false No
ignorestrictwarnings Boolean Whether to ignore strict warnings false No
allowencodingintosource Boolean Whether to allow encoding into the source tree false No
messageifnoloader String A valid PHP expression to customize the "no loader installed" message n/a No
actionifnoloader String A valid PHP expression to replace the "no loader installed" action n/a No
showcommandline Boolean whether to show command line before it is executed 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"
   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

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
tofile String File to write list of 'bad files' to. n/a No

Supported Nested Tags

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
suffix String Suffix to append to the filenames. -min No
failonerror Boolean Whether an error while minifying a JavaScript file should stop the build or not false No

Supported Nested Tags

LiquibaseChangeLogTask

The LiquibaseChangeLogTask writes the Change Log XML to copy the current state of the database to the given changeLogFile.

Example

<liquibase-changelog
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes

LiquibaseDbDocTask

The LiquibaseDbDocTask generates a Javadoc-like documentation based on current database and the given change log file.

Example

<liquibase-dbdoc
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
  outputDir="/tmp/generateddocs"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes
outputDir String Absolute path where the documentation gets written to. If the given directory does not exist, it get`s created automatically. n/a Yes

LiquibaseDiffTask

The LiquibaseDiffTask creates a diff between two databases. Will output the changes needed to convert the reference database to the state of the database.

Example

<liquibase-diff
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
  referenceUsername="liquibase"
  referencePassword="liquibase"
  referenceUrl="jdbc:mysql://localhost/refdatabase"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes
referenceUsername String The username needed to connect to the reference database. n/a Yes
referencePassword String The password needed for the given use to connect to the reference database. n/a Yes
referenceUrl String The JDBC Url representing the reference database datasource, e.g jdbc:mysql://localhost/refdatabase. n/a Yes

LiquibaseRollbackTask

The LiquibaseRollbackTask rolls back the database to the the state is was when the tag was applied.

Example

<liquibase-rollback
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
  rollbackTag="tag_0_1"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes
rollbackTag String The name of the tag to roll the database back to. n/a Yes

LiquibaseTagTask

The LiquibaseTagTask tags the current database state for future rollback.

Example

<liquibase-tag
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
  tag="tag_0_1"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes
tag String The name of the tag to apply. n/a Yes

LiquibaseUpdateTask

The LiquibaseUpdateTask applies the latest changes from the changelog file to the definied database.

Example

<liquibase-update
  jar="/usr/local/lib/liquibase/liquibase.jar"
  classpathref="/usr/local/lib/liquibase/lib/mysql-connector-java-5.1.15-bin.jar"
  changelogFile="./changelogTest.xml"
  username="liquibase"
  password="liquibase"
  url="jdbc:mysql://localhost/mydatabase"
/>

Attributes

Name Type Description Default Required
jar String Location of the Liquibase jar file. n/a Yes
classpathref String Additional classpath entries n/a Yes
changelogFile String Location of the changelog file in which the changes get written or read from. n/a Yes
username String The username needed to connect to the database. n/a Yes
password String The password needed for the given use to connect to the database. n/a Yes
url String The JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabase n/a Yes

MailTask

A task to send email.

NB: this task requires the PEAR Mail and Mail_Mime packages to send any attachments.

Example

<mail tolist="user@example.org" subject="build complete">The build process is a success...</mail>

Attributes

Name Type Description Default Required
from String Email address of sender. none Yes
tolist String Comma-separated list of recipients. none Yes
message String Message to send in the body of the email. none No
subject String Email subject line. none No

Supported Nested Tags

ParallelTask

Executes nested tasks in parallel.

WARNING: this task is highly experimental, and will only work on *nix machines that have the PHP pcntl extension installed.

<parallel threadCount="4">
    <echo>Job 1</echo>
    <echo>Job 2</echo>
    <echo>Job 3</echo>
    <echo>Job 4</echo>
</trycatch>

Attributes

Name Type Description Default Required
threadCount Integer Maximum number of threads / processes to use. n/a No

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
autocommit Boolean Whether to autocommit every single statement. false No
encoding String Encoding to use for read SQL files none No

Supported Nested Tags

PearPackageTask

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

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

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

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: pear.domain51.com.

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

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, openssl), used for this package. sha1 No
key String OpenSSL private key used to sign the phar package. n/a Yes, when using the openssl signature algorithm
keypassword String Password for the OpenSSL private key. No

Supported Nested Tags

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

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
encoding String The encoding of the files to check iso-8859-1 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
skipversioncheck Boolean Skips the version check when the task starts. false No

Supported Nested Tags

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>

PHPLocTask

This task runs phploc, a tool for measuring the size of PHP projects. You need an installed version of this tool (installable via PEAR) to use this task.

Attributes

Name Type Description Default Required
reportType String The type of the report. Available types are cli|csv|txt|xml. cli No
reportName String The name of the report type without a file extension. phploc-report No
reportDirectory String The directory to write the report file to. false Yes, when report type csv, txt or xml is defined.
countTests Boolean Flag to count the projects tests or not. false No
file String The name of the file to check. n/a Yes, when no nested fileset is defined.
suffixes String A comma-separated list of file suffixes to check. php No

Supported Nested Tags

Examples

<target name="-measure-and-log" description="Measures and logs the size of the project" hidden="true">
  <tstamp>
    <format property="check.date.time" pattern="%Y%m%d-%H%M%S" locale="en_US"/>
  </tstamp>
  <phploc reportType="txt" reportName="${check.date.time}-report"
          reportDirectory="phploc-reports">
    <fileset dir=".">
      <include name="**/*.php" />
      <include name="*.php" />
    </fileset>
  </phploc>
</target>

Checks the size of the project living in ${project.basedir} and writes the result as a txt report to ${project.basedir}/phploc-reports/${check.date.time}-report.txt.

<target name="project-size-and-tests" description="Measures the size of the project and count it's tests">
  <phploc countTests="true">
    <fileset dir=".">
      <include name="**/*.php" />
      <include name="*.php" />
    </fileset>
  </phploc>
</target>

Checks the size of the project living in ${project.basedir}, counts the project tests and writes/logs the result to the CLI.

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 Only when there are no nested fileset elements
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

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 Only when there are no nested fileset elements
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

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 Only when there are no nested fileset elements
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
debug Boolean Enable debug output? false No
haltonerror Boolean Stop the build process if errors occurred during the run. false No

Supported Nested Tags

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 is now deprecated in favor of the PhpDocumentor2Task.

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

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>

PhpDocumentor2Task

This task runs phpDocumentor 2 , PHP 5.3-compatible API documentation tool. This project is the result of the merge of the phpDocumentor and DocBlox projects.

Attributes

Name Type Description Default Required
title String Title of the project. n/a No
destdir String Destination directory for output files. n/a Yes
template String Name of the documentation template to use. responsive No
quiet Boolean Suppress chatter / warning messages. true No

Supported Nested Tags

Examples

<phpdoc2 title="API Documentation"
  destdir="apidocs"
  template="responsive">
   <fileset dir="./classes">
      <include name="**/*.php" />
   </fileset>
</phpdoc2>

PhpDocumentorExternalTask

This task is now deprecated in favor of the PhpDocumentor2Task.

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

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
processisolation Boolean Enable process isolation when executing tests. false No
configuration String Path to a PHPUnit configuration file (such as phpunit.xml). Supported elements are: bootstrap, processIsolation, stopOnFailure, stopOnError, stopOnIncomplete and stopOnSkipped. Values provided overwrite other attributes! n/a No

Supported Nested Tags

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.
If unspecified, the task will look for the stylesheet(s) in the following directories: the PHP include path, the Phing home directory and the PEAR data directory (if applicable).
n/a No
todir String An existing directory where the files resulting from the transformation should be written to. Yes
usesorttable boolean Whether to use the sorttable JavaScript library (see http://www.kryogenix.org/code/browser/sorttable/) false No

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.

rSTTask

Renders rST (reStructuredText) files into different output formats.

This task requires the python docutils installed. They contain rst2html, rst2latex, rst2man, rst2odt, rst2s5, rst2xml.

Homepage: https://gitorious.org/phing/rsttask

Features

Attributes

Name Type Description Default Required
file String rST input file to render n/a Yes (or fileset)
format String

Output format:

  • html
  • latex
  • man
  • odt
  • s5
  • xml
html No
destination String Path to store the rendered file to. Used as directory if it ends with a /. magically determined from input file No
uptodate Boolean Only render if the input file is newer than the target file false No
toolpath String Path to the rst2* tool determined from format No
toolparam String Additional commandline parameters to the rst2* tool n/a No
mode Integer The mode to create directories with. From umask No

Supported Nested Tags

Examples

Render a single rST file to HTML

By default, HTML is generated. If no target file is specified, the input file name is taken, and its extension replaced with the correct one for the output format.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="single">
  <target name="single" description="render a single rST file to HTML">

    <rST file="path/to/file.rst" />

  </target>
</project>

Render a single rST file to any supported format

The format attribute determines the output format:

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="single">
  <target name="single" description="render a single rST file to S5 HTML">

    <rST file="path/to/file.rst" format="s5" />

  </target>
</project>

Specifying the output file name

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="single">
  <target name="single" description="render a single rST file">

    <rST file="path/to/file.rst" destination="path/to/output/file.html" />

  </target>
</project>

Rendering multiple files

A nested fileset tag may be used to specify multiple files.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="multiple">
  <target name="multiple" description="renders several rST files">

    <rST>
     <fileset dir=".">
       <include name="README.rst" />
       <include name="docs/*.rst" />
     </fileset>
    </rST>

  </target>
</project>

Rendering multiple files to another directory

A nested mapper may be used to determine the output file names.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="multiple">
  <target name="multiple" description="renders several rST files">

    <rST>
     <fileset dir=".">
       <include name="README.rst" />
       <include name="docs/*.rst" />
     </fileset>
     <mapper type="glob" from="*.rst" to="path/to/my/*.xhtml"/>
    </rST>

  </target>
</project>

Modifying files after rendering

You may have variables in your rST code that can be replaced after rendering, i.e. the version of your software.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="filterchain">
  <target name="filterchain" description="renders several rST files">

    <rST>
     <fileset dir=".">
       <include name="README.rst" />
       <include name="docs/*.rst" />
     </fileset>
     <filterchain>
       <replacetokens begintoken="##" endtoken="##">
         <token key="VERSION" value="1.23.0" />
       </replacetokens>
     </filterchain>
    </rST>

  </target>
</project>

Rendering changed files only

The uptodate attribute determines if only those files should be rendered that are newer than their output file.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="multiple">
  <target name="multiple" description="renders several rST files">

    <rST uptodate="true">
     <fileset dir=".">
       <include name="docs/*.rst" />
     </fileset>
    </rST>

  </target>
</project>

Specify a custom CSS file

You may pass any additional parameters to the rst conversion tools with the toolparam attribute.

<?xml version="1.0" encoding="utf-8"?>
<project name="example" basedir="." default="single">
  <target name="single" description="render a single rST file to S5 HTML">

    <rST file="path/to/file.rst" toolparam="--stylesheet-path=custom.css" />

  </target>
</project>

S3PutTask

Uploads an object to Amazon S3. This task requires the PEAR package Services_Amazon_S3

Examples

Uploading a file

<s3put source="/path/to/file.txt" object="file.txt" bucket="mybucket" key="AmazonKey" secret="AmazonSecret" />

You can also define "bucket, key, secret" outside of the task call:

<property name="amazon.key" value="my_key" />
<property name="amazon.secret" value="my_secret" />
<property name="amazon.bucket" value="mybucket" />

<s3put source="/path/to/file.txt" object="file.txt" />
	

You can also specify inline content instead of a file to upload:

<property name="amazon.key" value="my_key" />
<property name="amazon.secret" value="my_secret" />
<property name="amazon.bucket" value="mybucket" />

<s3put content="Some content here" object="file.txt" />
	

It also works with filesets

<property name="amazon.key" value="my_key" />
<property name="amazon.secret" value="my_secret" />
<property name="amazon.bucket" value="mybucket" />
<s3put>
	<fileset dir="${project.basedir}">
		<include name="**/*.jpg" />
	</fileset>
</s3put>	
	

Attributes

Name Type Description Default Required
key String Amazon S3 key n/a Yes (or defined before task call as: amazon.key)
secret String Amazon S3 secret n/a Yes (or defined before task call as: amazon.secret)
bucket String Bucket to store the object in n/a Yes (or defined before task call as: amazon.bucket)
content String Content to store in the object n/a Yes (or source or fileset)
source String Where to read content for the object from n/a Yes (or content or fileset)
object String Object name n/a Yes (unless fileset)
contentType String Content type of the object, set to auto if you if you want to autodetect the content type based on the source file extension binary/octet-stream No

Supported Nested Tags

S3GetTask

Downloads an object from Amazon S3. This task requires the PEAR package Services_Amazon_S3

Examples

Downloading an object

<s3get object="file.txt" target="${project.basedir}" bucket="mybucket" key="AmazonKey" secret="AmazonSecret" />
			

You can also define "bucket, key, secret" outside of the task call:

<property name="amazon.key" value="my_key" />
<property name="amazon.secret" value="my_secret" />
<property name="amazon.bucket" value="mybucket" />

<s3get object="file.txt" target="${project.basedir}" />
			

Attributes

Name Type Description Default Required
key String Amazon S3 key n/a Yes (or defined before task call as: amazon.key)
secret String Amazon S3 secret n/a Yes (or defined before task call as: amazon.secret)
bucket String Bucket containing the object n/a Yes (or defined before task call as: amazon.bucket)
object String Object name n/a Yes
target String Where to store the object after download n/a Yes

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 (OpenSSH format) to use for the connection none No
privkeyfile String Private key file (OpenSSH format) 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
level String Control the level at which the task reports status messages. One of error, warning, info, verbose, debug. verbose No

Supported Nested Tags

SshTask

The SshTask 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 (OpenSSH format) to use for the connection none No
privkeyfile String Private key file (OpenSSH format) 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
property String The name of the property to capture (any) output of the command none No
display Boolean Whether to display the output of the command true No

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

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
trustServerCert Boolean Trust self-signed certificates 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
trustServerCert Boolean Trust self-signed certificates 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 copy to none Yes
recursive Boolean Recursive behavior True No
ignoreexternals Boolean Ignore externals definitions False No
trustServerCert Boolean Trust self-signed certificates 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
trustServerCert Boolean Trust self-signed certificates False No

SvnInfoTask

The SvnInfoTask parses the output of the 'svn info --xml' command and extracts one specified element (+ optional sub element) from that output.

Examples

<svninfo
   svnpath="/usr/bin/svn"
   workingcopy="/home/user/svnwc"
   element="url"
   propertyname="svn.url"/>
<svninfo
   repositoryurl="http://svn.phing.info/"
   element="commit"
   subelement="author"
   propertyname="svn.author"/>

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
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
propertyname String Name of property to use svn.info No
element String Sets whether to store actual last changed revision of the directory/file mentioned url No
subelement String Sets whether to force compatibility with older SVN versions (< 1.2) none 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
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
propertyname String Name of property to use svn.lastrevision No
lastChanged Boolean Sets whether to store actual last changed revision of the directory/file mentioned false No
forceCompatible Boolean Deprecated: Sets whether to force compatibility with older SVN versions (< 1.2) false No

SvnListTask

The SvnListTask stores the output of a svn list command on a workingcopy or repositoryurl in a property. The result will be stored in an array, one string that is separated by ' | ' (in words: space pipe space) for easy parsing.

Examples

<svnlist svnpath="/usr/bin/svn" workingcopy="/home/user/svnwc" propertyname="svn.list"/> 
<svnlist svnpath="/usr/bin/svn" repositoryurl="http://svn.example.com/myrepo/tags" orderDescending="true" limit="10" /> 

The latter example could produce a list of your tags like this:

revision | author | date         | item
4028     | tony   | May 19 18:31 | Release_2.9.1.7
4026     | tony   | May 18 14:33 | Release_2.9.1.6
4023     | tony   | May 16 15:53 | Release_2.9.1.5
4018     | tony   | May 13 11:55 | Release_2.9.1.4
4005     | tony   | Apr 27 12:09 | Release_2.9.1.3
...

Attributes

Name Type Description Default Required
svnpath String Path to Subversion binary /usr/bin/svn No
workingcopy String Working copy directory none One of the two
repositoryurl String URL of remote repository none
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
propertyname String Name of property to use svn.list No
forceCompatible Boolean Deprecated: Sets whether to force compatibility with older SVN versions (< 1.2) true No
limit Integer Limits the number of items to get back from the command n/a No
orderDescending Boolean Sets whether to reverse the order of the listed items false No

SvnLogTask

The SvnLogTask stores the output of a svn log command on a workingcopy or repositoryurl in a property. The result will be stored in an array, one string that is separated by ' | ' (in words: space pipe space) for easy parsing.

Examples

<svnlog svnpath="/usr/bin/svn" workingcopy="/home/user/svnwc" propertyname="svn.log"/> 
<svnlog svnpath="/usr/bin/svn" repositoryurl="http://svn.example.com/myrepo/trunk" limit="10" /> 

The latter example could produce a history of the latest revisions in the trunk:

4033 | tony  | 2011-05-23T14:21:12.496274Z  | some svn commit comment
4032 | tony  | 2011-05-23T13:24:46.496265Z  | some svn commit comment
4031 | tony  | 2011-05-23T09:23:28.093167Z  | some svn commit comment
...

Attributes

Name Type Description Default Required
svnpath String Path to Subversion binary /usr/bin/svn No
workingcopy String Working copy directory none One of the two
repositoryurl String URL of remote repository none
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
propertyname String Name of property to use svn.list No
forceCompatible Boolean Deprecated: Sets whether to force compatibility with older SVN versions (< 1.2) true No
limit Integer Limits the number of items to get back from the command n/a No

SvnUpdateTask

The SvnUpdateTask 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 the working copy none Yes
revision Integer Specific revision to update the working copy to none No
ignoreexternals Boolean Ignore externals definitions False No
trustServerCert Boolean Trust self-signed certificates False No

SvnSwitchTask

The SvnSwitchTask changes a local directory from one repository to another.

Examples

<svnswitch
   svnpath="/usr/bin/svn"
   username="anony"
   password="anony"
   nocache="true"
   repositoryurl="http://svn.phing.info/tags/2.4.2"
   todir="/home/user/svnwc"/>
<svnswitch
   svnpath="C:/Subversion/bin/svn.exe"
   repositoryurl="http://svn.phing.info/tags/2.4.2"
   todir="C:/projects/svnwc"/>

Attributes

Name Type Description Default Required
svnpath String Path to Subversion binary /usr/bin/svn No
repositoryurl String URL of remote repository none Yes
todir String Path to the checked out project 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
recursive Boolean Recursive behavior True No
ignoreexternals Boolean Ignore externals definitions False No
trustServerCert Boolean Trust self-signed certificates False No

SymfonyConsoleTask

Executes Symfony2 console commands

Examples

Simple example

            <SymfonyConsole command="cache:clear"/>
        

Complex example

            <SymfonyConsole command="cache:warmup">
                <arg name="env" value="prod" />
                <arg name="no-debug" />
                <arg value="some/path/or/single/value" quotes="true"/>
            </SymfonyConsole>
        

Attributes

Name Type Description Default Required
command string The Symfony Console command to execute n/a Yes
console string The path to symfony console application app/console no

Supported Nested Tags

SymlinkTask

Creates symlink(s) to a specified file / directory or a collection of files / directories.

Examples

Single symlink

<symlink target="/path/to/original/file" link="/where/to/symlink" />

Using filesets

<symlink link="/where/to/symlink">
	<fileset dir="/some/directory">
		<include name="*" />
	</fileset>
</symlink>
	

In the fileset example, assuming the contents of "/some/directory" were:

Then the contents of "/where/to/symlink" would be:

Attributes

Name Type Description Default Required
target String What you're trying to symlink from n/a Yes (or nested FileSet)
link String Where you'd like the symlink(s) n/a Yes
overwrite Boolean Whether to override the symlink if it exists but points to a different location false No

Supported Nested Tags

TarTask

The TarTask creates a tarball from a fileset or directory.

Examples

<tar destfile="phing.tar">
 <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.gz" basedir="." compression="gzip"/>

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

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

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
removepath String Path to remove from files in the archive(s) none No
forceExtract Boolean When set to false, only extract files if the destination does not exist yet or is older than the archive. When set to true, always extract files. false No

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
forceExtract Boolean When set to false, only extract files if the destination does not exist yet or is older than the archive. When set to true, always extract files. false No

Supported Nested Tags

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.

Note: This assumes that the DOM extension is loaded in PHP5 since this is used to drive the validation process.

Attributes

Name Type Description Default Required
schema String Path to XSD file n/a Yes
file String Path to XML file n/a No
haltonfailure Boolean Stops the build when validation fails true No
useRNG Boolean Set to Yes if the Schema is in the n Relax NG format false No

Supported Nested Tags

Example 1

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

Example 2

<fileset dir="./sources" id="sources">
  <include name="main.xml"/>
  <include name="chapter*.xml"/>
  <include name="appendix*.xml"/>
</fileset>
<property name="docbook.relaxng" value="/usr/share/xml/docbook/schema/rng/5.0/docbookxi.rng"/>

<xmllint schema="${docbook.relaxng}" useRNG="yes">
  <fileset refid="sources" />
</xmllint>

Validate a set of DocBook files against the DocBook RNG grammar

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
required Boolean Whether the XML file is required. false 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 separated 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

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.

ZendGuardEncodeTask

The ZendGuardEncodeTask is a wrapper for ZendGuard zendenc executable. It pre-compiles the PHP code which improves speed and can prevent unauthorized code modification. Additionally it allows signing or licensing the code so it can only be used with a valid license. 

For more information about ZendGuard encode parameters see the ZendGuard documentation.

Attributes

Name Type Description Default Required
zendEncoderPath String Path to  zendenc or zendenc5 binary. n/a Yes
deleteSource Boolean Whether to delete the original file and replace with encoded. true No
renameSourceExt String If defined the original file will be  copied to originalfile.renameSourceExt before encoding. This property overrides  the deleteSource property. n/a No
shortTags Boolean Turns on/off support for PHP short tags (<?). True to enable support. true No
aspTags Boolean Turns on/off support for ASP tags (<%). True to enable support. false No
noHeader Boolean Disables the PHP-compatible header that is added to the top of every encoded file by default and is displayed if the Zend Optimizer is not properly installed. false No
useCrypto Boolean Enables cryptography support. false No
encodedOnly Boolean If enabled the encoded files will only work with other encoded files ( I.e. encoded and not-encoded files cannot be used together). false No
forceEncode Boolean Allow encoding previously encoded files. Not recommended. false No
expires String Make an encoded file to expire on the given data. Date is in yyyy-mm-dd format. n/a No
obfuscationLevel Integer Level of obfuscation. Defaults to 0 (no obfuscation).  0 No
optMask Integer Optimization mask. Integer representing a bit mask. n/a No
privateKeyPath String Path to the company private key. This is required when either signProduct or licenseProduct is enabled. n/a No
licenseProduct Boolean Enabled product licensing. The encoded files won't work without a valid license. If enabled privateKeyPath property also needs to be defined. false No
signProduct Boolean Enabled product signing. If signing is enabled the files will be encoded with license support. However valid license won't be required for the files to work. If enabled privatKeyPath property also needs to be defined. false No
productName String Name of the product. This must match the product name in the license and is required when either licenseProduct or signProduct is enabled. n/a No
prologFile String Path to a file containing a text that will be prepended to each encoded file and displayed in case the Zend Optimizer is not installed. n/a No

Supported Nested Tags

Example

<zendguardencode
shortTags="false"
productName="Phing"
privateKeyPath="/var/data/phing.key"
licenseProduct="true"
zendEncoderPath="/usr/local/Zend/ZendGuard-5_0_1/bin/zendenc5"
>

<fileset dir="src">
<include name="**/*.php" />
<exclude name="cache/**" />
<exclude name="plugins/**" />
</fileset>

<fileset dir="src">
<include name="plugins/cs*/**/*.php" />
<include name="plugins/cs*/*.php" />
</fileset>
</zendguardencode>

Encode all php files in the current directory and subdirectories. Exlude everything in cache/ and plugins/ but include everything in plugins that starts with cs.

ZendGuardLicenseTask

The ZendGuardLicenseTask is a wrapper for ZendGuard zendenc_sign executable.  It generates ZendGuard license either from a license template file or from the defined properties.

For more information about ZendGuard sign parameters see the ZendGuard documentation.

Attributes

Name Type Description Default Required
zendsignPath String Path to  zendenc_sign binary. n/a Yes
privateKeyPath String Path to the company private key.  n/a Yes
outputFile String Path where should the license be generated. n/a Yes
licenseTemplate String Path to a license template file. If  defined all other licensing properties will be ignored (even if they are otherwise required). n/a No
productName String Name of the product. This has to match the product name that was used to encode the files (see ZendGuardEncodeTask). n/a Yes
registeredTo String Name to which the product will be registered to. n/a Yes
expires Mixed This allows to define when the license will expire.  The license can be issued so it either never expires or expires at a specified data.
Use:
  •  'Never', 0 or false to set expiry data to Never.
  • Date in yyyy-mm-dd format to set the expiry date to a specific date.
  • Relative format supported by strtotime function (e.g. '+6 months' to generate a license that will expire in half a year).
n/a Yes
ipRange String Limits the use of the license to IP addresses that fall within specification. Supports wildcards for any of the IP place holders, as well as the two types of the net masks (e.g. 10.1.0.0/16 or 10.1.0.0./255.255.0.0). n/a No
hardwareLocked Boolean Option that indicates if the license will be locked to a specific machine using the Zend Host ID code(s). If set to true the Host-ID property is required. false No
hostID String Coded string (Zend Host ID) used to lock the license to a specific hardware. The Zend Host Id obtained from the machine where the encoded files and license are to be installed. Can be obtained by using the zendid utility.

This is REQUIRED if the Hardware-Locked property is set to true. You can define multiple Host IDs separated by semicolon.
n/a No
userDefinedValues String Optional user defined values in format key=value. Multiple key-value pairs can be defined and separated by semicolon. These values then will be part of the license and can be obtained using the zend guard api (provided by Zend Optimizer). These values CANNOT be modified after the license is generated. Their modification would invalidate the license.
Example:  Drink=Tea;Material=Wood
n/a No
xUserDefinedValues String Optional user defined values in format key=value. Multiple key-value pairs can be defined and separated by semicolon. These values then will be part of the license and can be obtained using the zend guard api (provided by Zend Optimizer). These values CAN be modified after the license is generated. Their modification won't invalidate the license.
Example:  Drink=Tea;Material=Wood
n/a No

Examples
<zendguardlicense
privateKeyPath="/var/data/phing.key"
zendsignPath="/usr/local/Zend/ZendGuard-5_0_1/bin/zendenc_sign"
outputFile="./data/license/license.zl"
productName="Phing"
registeredTo="YourCustomerName"
hardwareLocked="true"
expires="+6 months"
HostID="H:MFM43-Q9CXC-B9EDX-GWYSU;H:MFM43-Q9CXC-B9EDX-GWYTY"
ipRange="10.1.*.*"
userDefinedValues="Drink=Tea;Material=Wood"
xUserDefinedValues="Drink=Tea;Material=Wood"
/>

Creates a license using the given properties.

<zendguardlicense
privateKeyPath="/var/data/phing.key"
zendsignPath="/usr/local/Zend/ZendGuard-5_0_1/bin/zendenc_sign"
outputFile="./data/license/license.zl"
licenseTemplate="./data/license/license.template.zl"
/>

Creates a license using a license template file.

ZipTask

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

Examples

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

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

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

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

Example

Attributes

Name Type Description Default Required
destfile String .ZIP filename n/a Yes
basedir String Base directory to zip (if no fileset specified, entire directory contents will be included in the archive) none No
prefix String File path prefix to use when adding files to zip none No
includeemptydirs Boolean If set to true, also empty directories are copied. true No

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

Supported Nested Tags