# Phing User Guide

2016-08-04

Preface
1. About this book
1.1. Authors
1.2. Copyright
1.3. License
1.4. DocBook
2. Introduction
2.1. What Phing Is
2.2. Phing & Binarycloud: History
2.3. How Phing Works
2.4. Cool, so how can I help?
3. Setting-up Phing
3.1. System Requirements
3.2. Obtaining Phing
3.3. PEAR Install
3.4. Composer Install
3.5. Other Install methods
3.6. Calling Phing
4. Getting started
4.1. XML And Phing
4.2. Writing A Simple Buildfile
4.3. More Complex Buildfile
4.4. Relax NG Grammar
5. Project components
5.1. Projects
5.2. Version
5.3. Project Components in General
5.4. Targets
5.5. Tasks
5.6. Types
5.7. Basic Types
5.8. Conditions
6. Extending Phing
6.1. Extension Possibilities
6.2. Source Layout
6.3. System Initialization
6.4. System Services
6.5. Build Lifecycle
6.6. Writing Tasks
6.7. Writing Types
6.8. Writing Mappers
A. Fact Sheet
A.1. Built-In Properties
A.2. Command Line Arguments
A.3. Distribution File Layout
A.4. Program Exit Codes
A.5. The LGPL License
A.6. The GFDL License
B. Core tasks
B.1. AdhocTaskdefTask
B.2. AdhocTypedefTask
B.3. AppendTask
B.4. ApplyTask
B.5. AttribTask
B.6. AvailableTask
B.7. Basename
B.8. ChmodTask
B.9. ChownTask
B.10. ConditionTask
B.11. CopyTask
B.12. CvsTask
B.13. CvsPassTask
B.14. DeleteTask
B.15. Diagnostics
B.16. Dirname
B.17. EchoTask
B.18. EchoPropertiesTask
B.19. ExecTask
B.20. FailTask
B.21. ForeachTask
B.22. IfTask
B.23. ImportTask
B.24. IncludePathTask
B.25. InputTask
B.26. LoadFileTask
B.27. MkdirTask
B.28. MoveTask
B.29. PathConvert
B.30. PhingTask
B.31. PhingCallTask
B.32. Phingversion
B.33. PhpEvalTask
B.34. PropertyTask
B.35. PropertyPromptTask
B.36. Record
B.37. ReflexiveTask
B.38. ResolvePathTask
B.39. Retry
B.40. SwitchTask
B.41. TaskdefTask
B.42. Tempfile Task
B.43. TouchTask
B.44. TryCatchTask
B.45. TstampTask
B.46. TypedefTask
B.47. UpToDateTask
B.48. WaitForTask
B.49. XsltTask
C. Optional tasks
C.1. ApiGenTask
C.2. AutoloaderTask
C.3. ComposerTask
C.4. CoverageMergerTask
C.5. CoverageReportTask
C.6. CoverageSetupTask
C.7. CoverageThresholdTask
C.8. DbDeployTask
C.9. ExportPropertiesTask
C.10. FileHashTask
C.11. FileSizeTask
C.12. FileSyncTask
C.13. FtpDeployTask
C.14. GitBranchTask
C.15. GitCheckoutTask
C.16. GitCloneTask
C.17. GitCommitTask
C.18. GitFetchTask
C.19. GitGcTask
C.20. GitInitTask
C.21. GitLogTask
C.22. GitMergeTask
C.23. GitPullTask
C.24. GitPushTask
C.25. GitTagTask
C.26. GitDescribeTask
C.27. GrowlNotifyTask
C.28. HgAddTask
C.29. HgArchiveTask
C.30. HgCloneTask
C.31. HgCommitTask
C.32. HgInitTask
C.33. HgLogTask
C.34. HgPullTask
C.35. HgPushTask
C.36. HgRevertTask
C.37. HgTagTask
C.38. HgUpdateTask
C.39. HttpGetTask
C.40. HttpRequestTask
C.41. IniFileTask
C.42. IoncubeEncoderTask
C.43. IoncubeLicenseTask
C.44. JsHintTask
C.45. JslLintTask
C.46. JsMinTask
C.47. LiquibaseTask
C.48. LiquibaseChangeLogTask
C.49. LiquibaseDbDocTask
C.50. LiquibaseDiffTask
C.51. LiquibaseRollbackTask
C.52. LiquibaseTagTask
C.53. LiquibaseUpdateTask
C.54. MailTask
C.55. ManifestTask
C.56. NotifySendTask
C.57. PackageAsPathTask
C.58. ParallelTask
C.59. PatchTask
C.60. PathToFileSetTask
C.61. PDOSQLExecTask
C.62. PearPackageTask
C.63. PearPackage2Task
C.64. PharDataTask
C.65. PharPackageTask
C.66. PhkPackageTask
C.67. PhpCodeSnifferTask
C.68. PHPCPDTask
C.69. PHPLocTask
C.70. PHPMDTask
C.71. PhpDependTask
C.72. PhpDocumentorTask
C.73. PhpDocumentor2Task
C.74. PhpDocumentorExternalTask
C.75. PhpLintTask
C.76. PHPUnitTask
C.77. PHPUnitReport
C.78. PropertyRegexTask
C.79. >ReplaceRegexpTask
C.80. rSTTask
C.81. S3PutTask
C.82. S3GetTask
C.83. SassTask
C.84. ScpTask
C.85. SmartyTask
C.86. SshTask
C.87. SimpleTestTask
C.88. SvnCheckoutTask
C.89. SvnCommitTask
C.90. SvnCopyTask
C.91. SvnExportTask
C.92. SvnInfoTask
C.93. SvnLastRevisionTask
C.94. SvnListTask
C.95. SvnLogTask
C.96. SvnUpdateTask
C.97. SvnSwitchTask
C.98. StopwatchTask
C.99. SymfonyConsoleTask
C.100. SymlinkTask
C.101. TarTask
C.102. ThrowTask
C.103. UntarTask
C.104. UnzipTask
C.105. VersionTask
C.106. WikiPublishTask
C.107. XmlLintTask
C.108. XmlPropertyTask
C.109. ZendCodeAnalyzerTask
C.110. ZendGuardEncodeTask
C.111. ZendGuardLicenseTask
C.112. ZipTask
C.113. ZSDTPackTask
C.114. ZSDTValidateTask
D. Core Types
D.1. Excludes
D.2. FileList
D.3. FileSet
D.4. PatternSet
D.5. Path / Classpath
D.6. PearPackageFileSet
E. Core filters
E.1. PhingFilterReader
E.2. ExpandProperties
E.3. ConcatFilter
E.4. HeadFilter
E.5. IconvFilter
E.6. Line Contains
E.7. LineContainsRegexp
E.8. PrefixLines
E.9. ReplaceTokens
E.10. ReplaceTokensWithFile
E.11. ReplaceRegexp
E.12. SortFilter
E.13. StripLineBreaks
E.14. StripLineComments
E.15. StripPhpComments
E.16. StripWhitespace
E.17. TabToSpaces
E.18. TailFilter
E.19. TidyFilter
E.20. XincludeFilter
E.21. XsltFilter
F. Core mappers
F.1. Common Attributes
F.2. ChainedMapper
F.3. CompositeMapper
F.4. FirstMatchMapper
F.5. CutDirsMapper
F.6. FlattenMapper
F.7. GlobMapper
F.8. IdentityMapper
F.9. MergeMapper
F.10. RegexpMapper
G. Core selectors
G.1. Contains
G.2. Date
G.3. Depend
G.4. Depth
G.5. Different
G.6. Filename
G.7. Present
G.8. Containsregexp
G.9. Size
G.10. Type
G.11. And
G.12. Majority
G.13. None
G.14. Not
G.15. Or
G.16. Readable
G.17. Writable
G.18. Selector
H. Project Components
H.1. Phing Projects
H.2. Targets
I. File Formats
I.1. Build File Format
I.2. Property File Format
Bibliography

# Preface

PHing Is Not GNU make; it's a PHP project build system or build tool based on Apache Ant. You can do anything with it that you could do with a traditional build system like GNU make, and its use of simple XML build files and extensible PHP "task" classes make it an easy-to-use and highly flexible build framework. Features include running PHPUnit and SimpleTest unit tests (including test result and coverage reports), file transformations (e.g. token replacement, XSLT transformation, Smarty template transformations), file system operations, interactive build support, SQL execution, CVS/SVN operations, tools for creating PEAR packages, documentation generation (DocBlox, PhpDocumentor) and much more.

If you find yourself writing custom scripts to handle the packaging, deploying, or testing of your applications, then we suggest looking at the Phing framework. Phing comes packaged with numerous out-of-the-box operation modules (tasks), and an easy-to-use OO model for adding your own custom tasks.

Phing provides the following high level features:

• Easy to read XML buildfiles

• Rich set of predefined tasks

• Easily extendible via PHP classes

• Platform-independent: works on UNIX, Windows, MacOSX

• No required external dependencies apart from a working PHP5 installation

• Built & optimized for ZendEngine2/PHP5

# Chapter 1 About this book

## 1.1 Authors

• Andreas Aderhold, andi@binarycloud.com

• Alex Black, enigma@turingstudio.com

• Manuel Holtgrewe, grin@gmx.net

• Hans Lellelid, hans@xmpl.org

• Michiel Rook, mrook@php.net

• Johan Persson, johan162@gmail.com

## 1.2 Copyright

Copyright 2002-2016, The Phing Project.

## 1.3 License

This documentation is made available under the GNU Free Document License (see Section A.6, “The GFDL License”)

Copyright (c) 2002 - 2016, The Phing Group

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation;

## 1.4 DocBook

All Phing reference documentation is written using the DocBook5 XML markup (see DocBook Project). The main advantage with DocBook is that it is a single source but multiple outputs. These document sources can be rendered into many possible output formats such as (X)HTML, PDF, EPub, Webhelp, RTF, Text and many more. Another advantage, inherit with the text based XML format, is that the document sources are all completely text based written using UTF-8 encoding. Only a plain text editor is required to extend or edit this documentation.

However, XML tends to be quite verbose and even if a plain text editor technically is all that is needed the actual entering of text will be made much easier with custom XML editor. These editors can be used to hide the XML tags and do auto-completion and on-the-fly validation to make sure that what is written is a valid DocBook5 document.

To work with the documentation we recommend to use one of the free XML/DocBook aware editors available. For example

The sources for the documentation are included under the docs/docbook5 directory. The DocBook sources are split into several files in order to make it more maintainable using the XML standard XInclude (see XML Inclusions (XInclude) Version 1.0).

For the writing of the book only a subset of all available DocBook elements are used as shown in Section 1.4.4, “DocBook v5 elements used in the manual and their meaning”

As of this writing the build process has been validated using version 1.78.1 of the DocBook5 stylesheets.

### Important

Make sure all documentation is written using UTF-8 text encoding.

### 1.4.1 Building the documentation

In order to build the documentation it is necessary to have the DocBook5 XSL stylesheets installed together with "xsltproc" which is used to transform the source into various output formats. In addition, to build the versions (either HTML or PDF) that supports highlighting of included source (within the <programlisting> element) the Saxon 6.5.5 XSL processor must be used. This is necessary since the syntax highlighting in DocBook is based on a Java extension (xslthl-2.x.x) which requires a Java based processor (such as Saxon).

### Tip

The easiest way to setup a complete build environment for DocBook5 for people new to DocBook is to install a clean version of Debian 7.x and then run the "deb-setup.sh" shell script. This will create a fully tested and working build environment for DocBook5 as it is used with Phing. This could easily be done using a virtual setup (for example using VirtualBox).

All DocBook sources are structured in a tree under docs/docbook5. The top level is the language of the manual. As of this writing only an English manual is available and hence the only top level directory available is "en". Under this directory the following structure applies (also for any new language translation that is added):

|-- scripts
|-- source
|   |-- appendixes
|   -- chapters
-- stylesheets
|-- css
|   -- img
-- xsl
-- images

All document sources are stored under the subdirectory "source" and the master document is aptly named "master.xml". This document pulls in all chapters and appendixes in the right order. For example, new tasks added should normally be documented in the "appendix/optionaltasks.xml" file. Look at the existing tasks and follow the same structure.

### Important

In order to get highlighting to work both the "xslthl-2.x.x.jar" package must be installed as well as Saxon 6.5.x. The jar file must be installed somewhere in the CLASSPATH , for example "/usr/share/java" if you run this on Linux. The xslthl package is available on SourceForge, please see XSLT syntax highlighting. By using the automated setup for Debian 7.x all these dependencies will be taken care of!

The customized stylesheets used are stored under "stylesheets" which uses one sub-folder for the customized XSL stylesheets (responsible for the transformation from DocBook to the chosen output format) and one sub-folder for the CSS stylesheets used to give the generated HTML documents there "look & feel".

Finally the "scripts" directory stores utility scripts. This currently contains two scripts, deb-setup.sh and "hlsaxon". The first scripts helps to create a full build environment for DocBook5 starting with a clean Debian 7 installation. This is meant to help people new to DocBook5 to get a working build environment as easy as possible. This script takes care of all detailed setup and will make a fulloy working DocBook5 build environment out-of-the-box.

The second script (hlsaxon) is wrapper file used from the buildfiles to call the Saxon translator (a Java based XSL procesor) with highlighting enabled and suitable paths to supporting libraries In this script the path to the DocBook installed stylesheets must be adjusted depending on your system (unless the automated setup have been used - with the deb-setup.sh file which takes care of that setup automatically). Mutatis mutandis.

In order to drive the transformation a Phing build script is available in the docbook root, build.xml. The build script supports the following public targets

 all*         Builds all available targets (default)
chunk        Builds the chunked HTML
clean        Removes all output files
epub         Builds the EPUB version
hlhtml       Builds the HTML version with syntax highlight
hlpdf        Builds the PDF version with syntax highlight
html         Builds the HTML version
htmlfancy    Builds the HTML version with an alternative styling for screen output
pdf          Builds the PDF version
webhelp      Builds the webhelp version (Note: This requires Java and Ant
to be installed!)
validate     Validates all sources against the DocBook5 grammar


All generated output is stored under the directory "output" (which is created if it doesn't exist) with a subdirectory corresponding to the name of the chosen output format.

### 1.4.2 Template for new tasks

For creating documentation for new tasks the easistes thing is to use the included template template_for_tasks.xml which is a skeleton tasks with all commonly used elements. This will ensure a correct setting of all attributes. The skeleton can then be added to a suitable appendix as needed.

### Note

All new task description should go into one of the Appendices.

### Note

The following section is only meant for the maintainers that work on the core layout of the official Phing manual and is not necessary for developers adding documentation for new tasks of improving documentation for existing tasks.

Furthermore, by necessity this assumes a rudimentary knowledge of Docbook5 bubild process and what XSL and CSS stylesheets are. It is not possible in this short space to give a full description of that setup.

XSL Customization layer

All DocBook5 renderings are started from one of the customized XSL stylesheet under "stylesheets/xsl" . All commonly adjusted properties should go into the appropriate stylesheet for that rendering. No properties should be passed on via the command line. To keep the customization layer as future proof as possible only in very rare circumstances should any cores XSL templates be copied and modified. As usual the recommended way is to use the provided hooks.

CSS styelsheets

The CSS stylesheets are used to create the look & feel for the HTML based renderings. These are entirely standard CSS files which by design are kept very simple. It should be noted that a few styling option depends in turn of the modified XSL transformations in the XSL customization layer. This had to be done in order to gain some more detialed control not provided by DocBook5 out-of-the-box.

Webhelp

The webhelp output rendering is a bit of a special case. This rendering depends not only on DocBook5 but also on Java as well as Ant build processor. These dependencies are inherited from the official DocBook5 webhelp process and will remain. Unfortunately adjusting the look & fell for this rendering is not as simple as for the other outputs since a fair amount of the layout (as well as look & feel) are hard-coded in the Webhelp build system. While it is perfectly possible to adjust the hard coded values and design choises it is not future proof. Since the Webhelp rendering is the newest and fastest improving output from DocBook the intention for the Phing documentation is to track these improvements and not spend time ourself to duplicate this effor with a parallell development.

### 1.4.4 DocBook v5 elements used in the manual and their meaning

To keep things simple the manual uses only a small subset of all available elements in the DocBook schema. This makes it fairly easy to quickly get up to speed with adding and editing the manual. It also helps to keep the look&feel consistent and makes the writing of the CSS and XSL stylesheets a little bit easer.

The following list shows the supported elements and how they should be used in the manual

<chapter>, <appendix>

This is the top element for each chapter and appendix in the manual. Each <chapter> or <appendix> must also have a title.

Table 1.1: Required attributes

AttributeValueDescription
xmlnshttp://docbook.org/ns/docbookName space for DocBook. Always needed.
xmlns:xihttp://www.w3.org/2001/XIncludeName space for XInclude. Needed since we use XInclude to split the manual into different files.
xmlns:xlinkhttp://www.w3.org/1999/xlinkName space for xlink. Needed sine we make use of link and xref elements to link to other sites and cross references within the manual.
version5.0Versions of DocBook. Always needed
xml:idapp.XXX , ch.XXXThe id for the chapter or the appendix. Used in other part of the manual to refer to this chapter/appendix with an <xref> element.

Table 1.2: Required nested elements

ElementValue
<title>The title of the chapter/appendix

Example:

<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="app.coretasks">
<title>Core tasks</title>
...
</appendix>
<sectN>

The section tags divides each chapter and appendix into logical parts. Each task description must be contained in a <sect1> element and each example section for the task must be contained within a <sect2> element. Depending on the description needed for each task additional <sect2> may be added as needed to make the text logically structured. If needed, a further nesting level may be used by using <sect3> elements within each <sect2> element. No deeper nestings than <sect3> should ever be used.

Each top level section must have the xml:id attribute which is used to reference the section from other parts of the document. Each section must have a nested title element.

Table 1.3: Required attributes

AttributeValueDescription
roletaskdefThis is only used and required for <sect1> elements for task description. This role is not currently used in the any of the XSL sheets. This is for future use.
xml:idName of sectionThe id for task definition should be the same as the task name for task description. For other sections the id should be a logical name that descrobes the content.

Table 1.4: Required nested elements

ElementValue
<title>The title of the section

Example:

<sect1 role="taskdef" xml:id="AdhocTaskdefTask">
<title>AdhocTaskdefTask</title>
...
</sect1>
<para>

Division between paragraphs in flowing text.

<screen>

Used to mark command lines and multi-line computer output. For inline screen output use the <literal> element

<programlisting>

Used for all PHP and XML program listings in the manual. Please note that this tag should not be used for command lines as entered in a terminal. Use the <screen> element for this.

Note: Remember to write all opening '<' as &lt;

Table 1.5: Required attributes

AttributeValueDescription
languagephp, xmlThe language attribute should indicate what programming language the programlisting contains. This is used to control what syntax highlighting should be used.

Example:

<programlisting language="xml">
<append
destFile="${process.outputfile}"> <filterchain> <xsltfilter style="${process.stylesheet}">
<param name="mode"
$> pear install phing/phing The pear installer will check any dependencies and place the phing script (phing or phing.bat) into your PHP script directoy (i.e. where the "pear" script resides). ## 3.4 Composer Install Install Phing by adding a dependency to phing/phing to the require-dev or require section of your project's composer.json configuration file, and running 'composer install':  { "require-dev": { "phing/phing": "2.*" } }  ## 3.5 Other Install methods If you are not using the PEAR installer, you will need to setup your environment in order to run Phing. The distribution of Phing consists of three directories: bin , docs and classes. Only the bin, classes and etc directories are required to run Phing. To install Phing, choose a directory and uncompress the distribution file in that directory (you may already have done this in a prior step). This directory will be known as PHING_HOME . ### Warning On earlier Windows installations, the script used to launch Phing will have problems if PHING_HOME is a long filepath. This is due to limitations in the OS's handling of the "for" batch-file statement. It is recommended, therefore, that Phing be installed in a short path, such as C:\opt\phing. Before you can run Phing there is some additional set up you will need to do perform: • Add the full path to the bin/ directory to your path. • Set the PHING_HOME environment variable to the directory where you installed Phing. On some operating systems the Phing wrapper scripts can guess PHING_HOME (Unix dialects and Windows). However, it is better to not rely on this behavior. • Set the PHP_COMMAND environment variable to where your Php binary is located (including the binary i.e. PHP_COMMAND=/usr/bin/php). • Set the PHP_CLASSPATH environment variable (see the section below). This should be set at least point to PHING_HOME/classes. Alternatively, you can also just add the phing/classes directory to your PHP include_path ini setting. • Check your php.ini file to make sure that you have the following settings: • max_execution_time = 0 // unlimited execution time • memory_limit = 32M // you may need more memory depending on size of your build files If you are using Phing in conjunction with another application, you may need to add additional paths to PHP_CLASSPATH. ### 3.5.1 Unix Assuming you are running a Unix dialect operating system with the bash bourne shell and Phing is installed in /opt/phing . The following sets up the environment properly: export PHP_COMMAND=/usr/bin/php export PHING_HOME=/opt/phing export PHP_CLASSPATH=${PHING_HOME}/classes
export PATH=${PATH}:${PHING_HOME}/bin

### 3.5.2 Windows

On the Windows platform, assuming Phing is installed in c:\opt\phing. The following sets up your environment:

set PHP_COMMAND=c:\opt\php\php.exe
set PHING_HOME=c:\opt\phing
set PHP_CLASSPATH=c:\opt\phing\classes
set PATH=%PATH%;%PHING_HOME%\bin

### 3.5.3 Advanced

There are lots of variants that can be used to run/prepare Phing. You need at least the following:

• If you want Phing to be able to use other packages / classes, you can either add them to the PHP_CLASSPATH or to PHP's include_path.

• Some Tasks in phing/tasks/ext may require 3rd party libraries to be installed. Generally, tools with compatible license (and stable releases) are included in phing/lib so that outside dependencies can be avoided. PEAR libs will not, however, be bundled with Phing since they are generally bundled with PHP. If you are using a 3rd party task, see the Task documentation to be aware of any dependencies.

You are now ready to use the phing command at your command prompt, from everywhere in your directory tree.

## 3.6 Calling Phing

Now you are prepared to execute Phing on the command line or via script files. The following section briefly describe how to properly execute phing.

### 3.6.1 Command Line

Phing execution on the command line is simple. Just change to the directory where your buildfile resides and type

$phing [target [target2 [target3] ...]] at the command line (where [target...] are the target(s) you want to be executed). If no target is specified Phing will try to execute the default target, as specified in the project tag. When calling multipe targets, Phing will invoke each target independently of the other targets. Optionally, you may specify command line arguments as listed in Appendix A. For example, the following command line calls the default buildscript build.xml using the default target with the property ftp.upload set to true. $ phing -Dftp.upload=true

### 3.6.2 Supported command line arguments

As of version 2.12.0 the following command line arguments are supported

  -h -help               print this message
-l -list               list available targets in this project
-v -version            print the version information and exit
-q -quiet              be extra quiet
-S -silent             print nothing but task outputs and build failures
-verbose               be extra verbose
-debug                 print debugging information
-emacs, -e             produce logging information without adornments
-diagnostics           print diagnostics information
-longtargets           show target descriptions during build
-logfile <file>        use given file for log
-logger <classname>    the class which is to perform logging
-f -buildfile <file>   use given buildfile
-D<property>=<value>   use value for given property
-keep-going, -k        execute all targets that do not depend
on failed target(s)
-propertyfile <file>   load all properties from file
-find <file>           search for buildfile towards the root of the
filesystem and use it
-inputhandler <file>   the class to use to handle user input

# Chapter 4 Getting started

Phing buildfiles are written in XML, and so you will need to know at least some basic things about XML to understand the following chapter. There is a lot of information available on the web:

## 4.1 XML And Phing

A valid Phing buildfile has the following basic structure:

• The document prolog

• Exactly one root element called <project> .

• Several Phing type elements (i.e. <property> , <fileset> , <patternset> etc.)

• One or more <target> elements containing built-in or user defined Phing task elements (i.e. <install> , <bcc> , etc).

## 4.2 Writing A Simple Buildfile

The Foobar project installs some PHP files from a source location to a target location, creates an archive of this files and provides an optional clean-up of the build tree:

<?xml version="1.0" encoding="UTF-8"?>

<project name="FooBar" default="dist">

<!-- ============================================  -->
<!-- Target: prepare                               -->
<!-- ============================================  -->
<target name="prepare">
<echo msg="Making directory ./build" />
<mkdir dir="./build" />
</target>

<!-- ============================================  -->
<!-- Target: build                                 -->
<!-- ============================================  -->
<target name="build" depends="prepare">
<echo msg="Copying files to build directory..." />

<echo msg="Copying ./about.php to ./build directory..." />
<copy file="./about.php" tofile="./build/about.php" />

<echo msg="Copying ./browsers.php to ./build directory..." />
<copy file="./browsers.php" tofile="./build/browsers.php" />

<echo msg="Copying ./contact.php to ./build directory..." />
<copy file="./contact.php" tofile="./build/contact.php" />
</target>

<!-- ============================================  -->
<!-- (DEFAULT)  Target: dist                       -->
<!-- ============================================  -->
<target name="dist" depends="build">
<echo msg="Creating archive..." />

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

<echo msg="Files copied and compressed in build directory OK!" />
</target>
</project>

A phing build file is normally given the name build.xml which is the default file name that the Phing executable will look for if no other file name is specified.

To run the above build file and execute the default target (assuming it is stored in the current directory with the default name) is only a matter of calling: $phing This will then execute the dist target. While executing the build file each task performed will print some information on what actions and what files have been affected. To run any of the other target is only a matter of providing the name of the target on the command line. So for example to run the build target one would have to execute $ phing build 

It is also possible to specify a number of additional command line arguments as described in Appendix A, Fact Sheet

### 4.2.1 Project Element

The first element after the document prolog is the root element named <project> on line 3. This element is a container for all other elements and can/must have the following attributes:

Table 4.1: <project> Attributes

AttributeDescriptionRequired
nameThe name of the projectNo
basedirThe base directory of the project, use "." do denote the current directory. Note: if none is specified, the parent directory of the build file is used!No
defaultThe default target that is to be executed if no target(s) are specified when calling this build file.Yes
descriptionThe description of the project.No

See Section H.1, “Phing Projects” for a complete reference.

### 4.2.2 Target Element

A target can depend on other targets. You might have a target for installing the files in the build tree, for example, and a target for creating a distributable tar.gz archive. You can only build a distributable when you have installed the files first, so the distribute target depends on the install target. Phing resolves these dependencies.

It should be noted, however, that Phing's depends attribute only specifies the order in which targets should be executed - it does not affect whether the target that specifies the dependency(s) gets executed if the dependent target(s) did not (need to) run.

Phing tries to execute the targets in the depends attribute in the order they appear (from left to right). Keep in mind that it is possible that a target can get executed earlier when an earlier target depends on it, in this case the dependent is only executed once:

<target name="A" />
<target name="B" depends="A" />
<target name="C" depends="B" />
<target name="D" depends="C,B,A" />

Suppose we want to execute target D. Looking at its depends attribute, you might think that first target C, then B and then A is executed. Wrong! C depends on B, and B depends on A, so first A is executed, then B, then C, and finally D.

A target gets executed only once, even when more than one target depends on it (see the previous example).

The optional description attribute can be used to provide a one-line description of this target, which is printed by the -projecthelp command-line option.

#### Target attributes

You can specify one or more of the following attributes within the target element.

Table 4.2: <target> Attributes

AttributeDescriptionRequired
nameThe name of the targetYes
dependsA comma-separated list of targets this target depends on.No
ifThe name of the Property that has to be set in order for this target to be executedNo
unlessThe name of the Property that must not be set in order for this target to be executed.

See Section H.2, “Targets” for a complete reference.

### 4.2.3 Task Elements

A task is a piece of PHP code that can be executed. This code implements a particular action to perform (i.e. install a file). Therefore it must be defined in the buildfile so that it is actually invoked by Phing.

These references will be resolved before the task is executed.

Tasks have a common structure:

<name attribute1="value1" attribute2="value2" ... />

where name is the name of the task, attributeN is the attribute name, and valueN is the value for this attribute.

There is a set of core tasks (see Appendix B, Core tasks) along with a number of optional tasks. It is also very easy to write your own tasks (see Chapter 6, Extending Phing).

Tasks can be assigned an id attribute:

<taskname id="taskID" ... />

By doing this you can refer to specific tasks later on in the code of other tasks.

### 4.2.4 Property Element

Properties are essentially variables that can be used in the buildfile. These might be set in the buildfile by calling the property task, or might be set outside Phing on the command line (properties set on the command line always override the ones in the buildfile). A property has a name and a value only. Properties may be used in the value of task attributes. This is done by placing the property name between " ${ " and " } " in the attribute value. For example, if there is a BC_BUILD_DIR property with the value 'build', then this could be used in an attribute like this: ${BC_BUILD_DIR}/en . This is resolved to build/en.

Phing provides access to system properties as if they had been defined using a <property> task. For example, ${os.name} expands to the name of the operating system. See Appendix A, Fact Sheet for a complete list ## 4.3 More Complex Buildfile <?xml version="1.0" encoding="UTF-8" ?> <project name="testsite" basedir="." default="main"> <property file="./build.properties" /> <property name="package" value="${phing.project.name}" override="true" />
<property name="builddir" value="./build/testsite" override="true" />
<property name="srcdir"   value="${project.basedir}" override="true" /> <!-- Fileset for all files --> <fileset dir="." id="allfiles"> <include name="**" /> </fileset> <!-- ============================================ --> <!-- (DEFAULT) Target: main --> <!-- ============================================ --> <target name="main" description="main target"> <copy todir="${builddir}">
<fileset refid="allfiles" />
</copy>
</target>

<!-- ============================================  -->
<!-- Target: Rebuild                               -->
<!-- ============================================  -->
<target name="rebuild" description="rebuilds this package">
<delete dir="${builddir}" /> <phingcall target="main" /> </target> </project> This build file first defines some properties with the <property> task call to PropertyTask. Then, it defines a fileset and two targets. Let us have a quick rundown of this build file. The first four tags within the project tag define properties. They appear in two possible variants: • The first property tag contains only the file attribute. The value has to be a relative or absolute path to a property file (for the format, see Appendix I, File Formats). • The other times, the tag has a name and a value attribute. After the call, the value defined in the attribute value is available through the key enclosed in "${" and "}".

The next noticeable thing in the build file is the <fileset> tag. It defines a fileset, i.e. a set of multiple files. You can include and exclude files with the include and exclude tags within the fileset tag. For more information concerning Filesets (i.e. Patterns) see Appendix D, Core Types. The fileset is given an id attribute, so it can be referenced later on.

One thing is worth noting here though and that is the use of double star expression, i.e. "**". This special regexp refers to all files in all subdirectories as well. Compare this with a single "*" which would only refer to all files in the current subdirectory. So for example the expression "**/*.phps" would refer to all files with suffix "'.phps" in all subdirectories below the current directory.

The first task only contains a call to CopyTask via <copy>. The interesting thing is within the copy tag. Here, a fileset task is not written out with nested include or exclude elements, but via the refid, the Fileset created earlier is referenced. This way, you can use a once defined fileset multiple times in your build files.

The only noticeable thing in the second target is the call to PhingTask with the <phingcall> tag (see Appendix B, Core tasks for more information). The task executes a specified target within the same build file. So, the second target removes the build directory and calls main again, thus rebuilding the project.

A variant is to override properties defined in the build file with properties specified on the command line using the -D switch. For example to override the builddir in the build file above one could call Phing as

$phing -Dbuilddir=/tmp/system-test  ### 4.3.1 Handling source dependencies A common task required in many build files is to keep some target which has a number of dependencies up to date. In traditional make files this could for example be an executable that needs to be recompiled if any of the source files have been updated. In Phing such a condition is handled by the UpToDateTask , see Section B.47, “UpToDateTask ” for examples on how this task us used. ## 4.4 Relax NG Grammar With a little bit of experience it is not that difficult to write and understand Phing build files since the XML format in itself tends to be quite verbose. However, it can become a bit tedious and the large (and growing) amount of built-in tasks and filters can sometimes make it difficult to remember the exact syntax of all the available features. To help with this the Phing distribution contains a Relax NG Grammar (REgular LAnguage for XML Next Generation, http://www.relaxng.org/) file that describes the (formal) syntax of the build files. This grammar can be used to validate build files. However, the most beneficial use of the grammar is together with a schema aware XML editor. Such an editor can make auto-completion based on the grammar. This feature makes writing complex build files significantly easier since it is usually enough to enter the first letter of an element to have the rest of the element written automatically as well as any compulsory attributes. Most XML editors can be told to what schema (or model) to use for validation and auto-completion by adding a specification in the beginning of the XML file. For example, the following two lines in the beginning of an XML file would do (of course the exact path to the grammar will depend on your system setup) <?xml version="1.0" encoding="UTF-8"?> <?xml-model xlink:href="/usr/share/php5/PEAR/data/phing/etc/phing-grammar.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0" ?> Using auto-completion will make it substantially easier to edit large build files. Please note that since the phing-grammar does not have an official designation we must use the absolute filename to specify the grammar (instead of a canonical URI that is resolved by the systems XML-catalogue). This grammar is available (as a plain text file) in the distribution at: /etc/phing-grammar.rng Since we do not want to neither endorse nor forget any particular XML editor with this capability we do not make available such a list of editors. Instead, spending a few minutes with Google searching for XML-editors is bound to find a number of editors with this capability. If you wish to validate your Phing build file, there are numerous options. Links to various validation tools and XML editors are available at the RELAX NG home page, http://www.relaxng.org/. The command line tool xmllint that comes with libxml2 is also able to validate a given XML file against the supplied grammar. For example, to use xmllint to validate a Phing build file the following command line could be used: $ xmllint -noout -relaxng phing-grammar.rng build.xml
build.xml validates

# Chapter 5 Project components

This goal of this chapter is to make you familiar with the basic components of a buildfile. After reading this chapter, you should be able to read and understand the basic structure of any buildfile even if you don't know exactly what the individual pieces do.

For supplemental reference information, you should see Appendix B, Core tasks, Appendix D, Core Types and Appendix H, Project Components.

## 5.1 Projects

In the structure of a Phing buildfile, there must be exactly one Project defined; the <project> tag is the root element of the buildfile, meaning that everything else in the buildfile is contained within the <project > element.

<?xml version="1.0"?>

<project name="test" description="Simple test build file" default="main" >
<!-- Everything else here -->
<project>

The listing above shows a sample <project> tag that has all attributes available for Projects. The name and description attributes are fairly self-explanatory; the default attribute specifies the default Target to execute if no target is specified (Section H.2, “Targets” are described below). For a complete reference, see Appendix H, Project Components.

## 5.2 Version

Since Phing 2.4.2 it is possible to include a phingVersion attribute in the <project> tag. This attribute allows you to define the minimum Phing version required to execute a build file, in order to prevent compatibility issues.

<?xml version="1.0"?>

<project name="test" phingVersion="2.4.2" >
<!-- Everything else here -->
<project>

## 5.3 Project Components in General

Project Components are all the elements found inside a project, i.e. targets, tasks, types, etc. Project components may have attributes and nested tags. Attributes only contain simple values, i.e. strings, integers etc. Nested elements may be complex Phing types (like FileSets) or simple wrapper classes for values with custom keys (see Appendix D, Core Types for example).

Any nested elements must be supported by the class that implements the project component, and because the nested tags are handled by the project component class the same nested tag may have different meanings (and different attributes) depending on the context. So, for example, the nested tag <param.../> within the <phingcall> tag is handled very differently from the<param.../> tag within the <xsltfilter> tag -- in the first case setting project properties, in the second case setting XSLT parameters.

## 5.4 Targets

Targets are collections of project components (but not other targets) that are assigned a unique name within their project. A target generally performs a specific task -- or calls other targets that perform specific tasks -- and therefore a target is a bit like a  function (but a target has no return value).

Targets may depend on other targets. For example, if target A depends on a target B, then when target A is called to be executed, target B will be executed first. Phing automatically resolves these dependencies. You cannot have circular references like: "target A depends on target B that depends on target A".

The following code snippet shows an example of the use of targets.

<target name="othertask" depends="buildpage" description="Whatever">
<!-- Task calls here -->
<target>

<target name="buildpage" description="Some description">
<!-- Task calls here -->
<target>

When Phing is asked to execute the othertask target, it will see the dependency and execute buildpage first. Notice that the dependency task can be defined after the dependent task.

## 5.5 Tasks

Tasks are responsible for doing the work in Phing. Basically, tasks are the individual actions that your buildfile can perform. For example, tasks exist to copy a file, create a directory, TAR files in a directory. Tasks may also be more complex such as XsltTask which copies a file and transforms the file using XSLT, SmartyTask which does something similar using Smarty templates, or CreoleTask which executes SQL statements against a specified DB. See Appendix B, Core tasks for descriptions of Phing tasks.

Tasks support parameters in the form of:

• Simple parameters (i.e. strings) passed as XML attributes, or

• More complex parameters that are passed by nested tags

Simple parameters are basically strings. For example, if you pass a value "A simple string." as a parameter, it is evaluated as a string and accessible as one. You can also reference properties as described in Chapter 4, Getting started.

Note: There are special values that are not mapped to strings, but to boolean values instead. The values true, false, yes, no, on and off are translated to true/false boolean values.

<property name="myprop" value="value" override="true"/>

However, some tasks support more complex data types as parameters. These are passed to the task with nested tags. Consider the following example:

<copy>
<fileset dir=".">
<include name="**" />
</fileset>
</copy>

Here, CopyTask is passed a complex parameter, a Fileset. Tasks may support multiple complex types in addition to simple parameters. Note that the names of the nested tags used to create the complex types depend on the task implementation. Tasks may support default Phing types (see Section 5.6, “ Types ”) or may introduce other types, for example to wrap key/value pairs.

Refer to Appendix B, Core tasks for a list of system tasks and their parameters.

## 5.6 Types

### 5.6.1 Basics

Besides the simple types (strings, integer, booleans) you can use in the parameters of tasks, there are more complex Phing Types. As mentioned above, they are passed to a task by using nesting tags:

<task>
<type />
</task>

<!-- or: -->

<task>
<type1>
<subtype1>
<!-- etc. -->
</subtype1>
</type1>
</task>

Note that types may consist of multiple nested tags -- and multiple levels of nested tags, as you can see in the second task call above.

### 5.6.2 Referencing Types

An additional fact about types you should notice is the possibility of referencing type instances, i.e. you define your type somewhere in your build file and assign an id to it. Later, you can refer to that type by the id you assigned. Example:

<project>
<fileset id="foo">
<include name="*.php" />
</fileset>

<!-- Target that uses the type -->
<target name="foo" >
<copy todir="/tmp">
<fileset refid="foo" />
</copy>
</target>
</project>

As you can see, the type instance is assigned an id with the id attribute and later on called by passing a plain fileset tag to CopyTask that only contains the refid attribute.

## 5.7 Basic Types

The following section gives you a quick introduction into the basic Phing types. For a complete reference see Appendix D, Core Types.

### 5.7.1 FileSet

FileSets are groups of files. You can include or exclude specific files and patterns to/from a FileSet. The use of patterns is explained below. For a start, look at the following example:

<fileset dir="/tmp" id="fileset1">
<include name="sometemp/file.txt" />
<include name="othertemp/**" />
<exclude name="othertemp/file.txt" />
</fileset>

<fileset dir="/home" id="fileset2">
<include name="foo/**" />
<include name="bar/**/*.php" />
<exclude name="foo/tmp/**" />
</fileset>

The use of patterns is quite straightforward: If you simply want to match a part of a filename or dirname, you use *. If you want to include multiple directories and/or files, you use **. This way, filesets provide an easy but powerful way to include files.

### 5.7.2 FileList

FileLists, like FileSets, are collections of files; however, a FileList is an explicitly defined list of files -- and the files don't necessarily have to exist on the filesystem.

Besides being able to refer to nonexistent files, another thing that FileLists allow you to do is specify files in a certain order. Files in FileSets are ordered based on the OS-level directory listing functions, in some cases you may want to specify a list of files to be processed in a certain order -- e.g. when concatenating files using the <append> task.

<filelist dir="base/" files="file1.txt,file2.txt,file3.txt"/>

<!-- OR: -->
<filelist dir="basedir/" listfile="files_to_process.txt"/>

### 5.7.3 FilterChains and Filters

FilterChains can be compared to Unix pipes. Unix pipes add a great deal of flexibility to command line operations; for example, if you wanted to copy just those lines that contained the string blee from the first 10 lines of a file called foo to a file called bar, you could do:

cat foo | head -n10 | grep blee > bar

Something like this is not possible with the tasks and types that we have learned about thus far, and this is where the incredible usefulness of FilterChains becomes apparent. They emulate Unix pipes and provide a powerful dimension of file/stream manipulation for the tasks that support them.

FilterChain usage is quite straightforward: you pass the complex Phing type filterchain to a task that supports FilterChains and add individual filters to the FilterChain. In the course of executing the task, the filters are applied (in the order in which they appear in the XML) to the contents of the files that are being manipulated by your task.

<filterchain>
<replacetokens>
<token key="BC_PATH" value="${top.builddir}/"/> <token key="BC_PATH_USER" value="${top.builddir}/testsite/user/${lang}/"/> </replacetokens> <filterreader classname="phing.filters.TailFilter"> <param name="lines" value="10"/> </filterreader> </filterchain> The code listing above shows you some example of how to use filter chains. For a complete reference see Appendix D, Core Types. This filter chain would replace all occurrences of BC_PATH and BC_PATH_USER with the values assigned to them in lines 4 and 5. Additionally, it will only return the last 10 lines of the files. Notice above that FilterChain filters have a "shorthand" notation and a long, generic notation. Most filters can be described using both of these forms: <replacetokens> <token key="BC_PATH" value="${top.builddir}/"/>
<token key="BC_PATH_USER" value="${top.builddir}/testsite/user/${lang}/"/>
</replacetokens>

<!-- OR: -->

<filterreader classname="phing.filters.ReplaceTokens">
<hgarchive destination="${version}.tgz" /> ## C.30 HgCloneTask Make a copy of an existing Mercurial repository. This is available for PHP 5.4 and higher. Table C.31: Attributes NameTypeDescriptionDefaultRequired insecureBooleanDo not verify server certificate.falseNo repositoryStringPath to Mercurial repository.n/aYes targetPathStringDirectory to clone into.n/aYes quietBooleanWork silently unless an error occurs.falseNo ### C.30.1 Example <property name="repo.dir" value="./repo.directory" /> <property name="repo.url" value="https://bitbucket.org/spaetz/ceyx-mapcss" /> <resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" />
<hgclone repository="${repo.url}" quiet="false" insecure="true" targetPath="${repo.dir.resolved}"/> 

## C.31 HgCommitTask

Commit changes to a Mercurial repository. This is available for PHP 5.4 and higher.

Table C.32: Attributes

NameTypeDescriptionDefaultRequired
messageStringCommit message.n/aYes
quietBooleanWork silently unless an error occurs.falseNo
repositoryStringPath to Mercurial repository.n/aNo
userStringUser to record as the committer.n/aNo

### C.31.1 Example

<property name="repo.dir" value="./repo.directory" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" /> <hgcommit message="[ci skip] Compress .js files." user="phingbot" repository="${repo.dir.resolved}"/> 

## C.32 HgInitTask

Create a new Mercurial repository. This is available for PHP 5.4 and higher.

Table C.33: Attributes

NameTypeDescriptionDefaultRequired
insecureBooleanDo not verify server certificate.falseNo
quietBooleanWork silently unless an error occurs.falseNo
repositoryStringPath to Mercurial repository.n/aNo

### C.32.1 Example

<property name="repo.dir" value="./repo.directory" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" /> <hginit repository="${repo.dir.resolved}"/> 

## C.33 HgLogTask

Show revision history of entire Mercurial repository or files, or limit to a number of revisions. Optionally store the history to a phing property. This is available for PHP 5.4 and higher.

Table C.34: Attributes

NameTypeDescriptionDefaultRequired
formatStringDisplay with template, e.g. "{rev}\n", "{branch}" etc.n/aNo
maxCountIntegerNumber of commits to show/limit.n/aNo
outputPropertyStringProperty name to set output value to from the execution.n/aNo
repositoryStringPath to Mercurial repository.n/aYes
revisionStringShow the specified revision or range.n/aYes

### C.33.1 Example

<property name="repo.dir" value="./repo.directory" />
<resolvepath propertyName="repo.dir.resolved" file="${repo.dir}" /> <hglog maxCount="1" format="{files}\n" outputproperty="hgfiles" repository="${repo.dir.resolved}"/> 

## C.34 HgPullTask

Pull changes from a specified Mercurial repository to a local one. This is available for PHP 5.4 and higher.

Table C.35: Attributes

NameTypeDescriptionDefaultRequired
insecureBooleanDo not verify server certificate.falseNo
quietBooleanWork silently unless an error occurs.falseNo
repositoryStringPath to Mercurial repository.n/aNo

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

Table C.40: Attributes

NameTypeDescriptionDefaultRequired
urlStringThe request URLn/aYes
dirStringThe directory to save the filen/aYes
filenameStringThe filename for the downloaded fileThe filename part of the URLNo
followRedirectsBooleanWhether to follow HTTP redirectsfalseNo
sslVerifyPeerBooleanWhether to verify SSL certificatestrueNo
authUserStringThe authentication user namen/aNo
authPasswordStringThe authentication passwordn/aNo
authSchemeStringThe authentication schemebasicNo

### C.39.1 Example

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

### C.39.2 Supported Nested Tags

• config

Holds additional config data. See HTTP_Request2 documentation for supported values.

Table C.41: Attributes

NameTypeDescriptionDefaultRequired
nameStringConfig parameter namen/aYes
valueMixedConfig valuen/aYes

• header

Holds additional header name and value.

Table C.42: Attributes

NameTypeDescriptionDefaultRequired
nameStringHeader namen/aYes
valueStringHeader valuen/aYes

### C.39.3 Global configuration

In addition to configuring a particular instance of HTTP_Request2 via nested <config> tags it is also possible to set default configuration values for HttpGetTask / HttpRequestTask by setting phing.http.* properties.

<property name="phing.http.proxy" value="socks5://localhost:1080/"/>
<!-- This request will go through the default proxy -->
<httpget url="http://example.com/file.zip" dir="./"/>
<httpget url="http://example.org/file.exe" dir="./">
<!-- This proxy will be used instead of the default one -->
<config name="proxy" value="http://foo:bar@proxy.example.org:3128/"/>
</httpget>


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

Table C.43: Attributes

NameTypeDescriptionDefaultRequired
urlStringThe request URLn/aYes
responseRegexStringThe regular expression for matching the responsen/aNo
authUserStringThe authentication user namen/aNo
authPasswordStringThe authentication passwordn/aNo
authSchemeStringThe authentication schemebasicNo
verboseBooleanWhether to enable detailed loggingfalseNo
observerEventsStringComma-separated list of events to log when verbose is set to trueconnect, sentHeaders, sentBodyPart, receivedHeaders, receivedBody, disconnectNo
methodStringThe HTTP method of the request, currently only GET or POST supportedGETNo

### C.40.1 Example

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

<http-request
url="http://my-production.example.com/check-deployment.php"
verbose"true"
method="POST">
<postparameter name="param1" value="value1" />
<postparameter name="param2" value="value2" />
</http-request>


Perform an HTTP POST request to the given URL. Setting POST request parameters to emulate form submission.

### C.40.2 Supported Nested Tags

• config

Holds additional config data. See HTTP_Request2 documentation for supported values.

Table C.44: Attributes

NameTypeDescriptionDefaultRequired
nameStringConfig parameter namen/aYes
valueMixedConfig valuen/aYes

• header

Holds additional header name and value.

Table C.45: Attributes

NameTypeDescriptionDefaultRequired
nameStringHeader namen/aYes
valueStringHeader valuen/aYes

• postparameter

Used when performing a POST request. Contains name and value of a form field.

Table C.46: Attributes

NameTypeDescriptionDefaultRequired
nameStringField namen/aYes
valueStringField valuen/aYes

### C.40.3 Global configuration

In addition to configuring a particular instance of HTTP_Request2 via nested <config> tags it is also possible to set default configuration values for HttpGetTask / HttpRequestTask by setting phing.http.* properties.

<property name="phing.http.proxy" value="socks5://localhost:1080/"/>
<!-- This request will go through the default proxy -->
<http-request url="http://example.com/foo"/>
<http-request url="http://example.org/restricted" dir="./">
<!-- This proxy will be used instead of the default one -->
<config name="proxy" value="http://foo:bar@proxy.example.org:3128/"/>
</http-request>


## C.41 IniFileTask

The IniFileTask is inspired by the Ant-Contrib IniFile and can be used to build and edit .ini files.

Table C.47: Attributes

NameTypeDescriptionDefaultRequired
deststringThe name of the .ini file to write to. If not specified, the source file will be modified instead.noneNo
haltOnErrorbooleanShould the build fail when problems occur?falseNo
sourcestringThe name of the .ini file to read from. If not specified, the dest file will be used instead.noneNo

### C.41.1 Supported Nested Tags

• remove

Use to remove either a specific key or section from an .ini file

Table C.48: Attributes

NameTypeDescriptionDefaultRequired
sectionStringName of the section.n/aYes
propertyStringName of the key to remove. If not specified the entire section is removed.n/aNo

• set

Use to set a key in a section to a specific value

Table C.49: Attributes

NameTypeDescriptionDefaultRequired
sectionStringName of the section.n/aYes
propertyStringName of the key/property.n/aYes
operationStringThe operation to perform on the existing value, which must be numeric. Possible values are "+" and "-", which add and subtract 1, respectively from the existing value. If the value doesn't already exist, the set is not performed, triggering an error.n/aNo
valueStringThe new value for the property.n/aNo, if operation is specified.

### C.41.2 Example

<inifile
haltonerror="no"
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> ### C.62.2 Supported Nested Tags • fileset • option • mapping The <mapping> tag represents a complex data type. You can use nested <mapping> (and nested <element> with <element> tags) to represent the full complexity of the structure. Bear in mind that what you are creating will be mapped to an associative array that will be passed in via PEAR_PackageFileMaintainer::setOptions() . <mapping name="option_name"> <element key="key_name" value="key_val"/> <element key="key_name" value="key_val"/> </mapping> • role See PEAR_PackageFileManager::addRole for more information. Table C.75: Available options NameTypeDescriptionDefaultRequired extensionStringThe file extensionn/aYes roleStringThe file extensionn/aYes ## C.63 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. Table C.76: Attributes NameTypeDescriptionDefaultRequired nameStringThe name of the PEAR package.n/aYes dirStringThe base directory of files to add to package.n/aYes ### C.63.1 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> ### C.63.2 Supported Nested Tags • fileset • option Table C.77: Available options NameTypeDescriptionDefaultRequired summaryString n/aYes descriptionString n/aYes licenseString n/aYes channelStringChannel name (not alias!). Must be registered (pear channel-discover channel) on the machine, where the build will be.n/aYes apiversionString n/aYes releaseversionString n/aYes releasestabilityStringOne from: snapshot, devel, alpha, beta or stable.n/aYes apistabilityStringOne from: devel, alpha, beta or stable.n/aYes noteString n/aYes packagetypeString n/aYes phpdepString n/aYes pearinstallerdepString n/aYes • mapping The <mapping> tag represents a complex data type. You can use nested <mapping> (and nested <element> with <element> tags) to represent the full complexity of the structure. Bear in mind that what you are creating will be mapped to an associative array that will be passed in via PEAR_PackageFileMaintainer::setOptions() . <mapping name="option_name"> <element key="key_name" value="key_val"/> <element key="key_name" value="key_val"/> </mapping> Available mappings and they structures: • deps (optional) see PEAR_PackageFileManager::addDependency() for more info Table C.78: Parameters NameTypeDescriptionDefaultRequired channelStringChannel name, from package is.n/aYes nameStringPackage name in channel.n/aYes versionStringMinimal version.n/aYes maxStringMaximum version.Same as version.No recommendedStringRecommended version.Same as version.No • extdeps (optional) see PEAR_PackageFileManager::addDependency() for more info Table C.79: Parameters NameTypeDescriptionDefaultRequired nameStringPackage name.n/aYes versionStringMinimal version.n/aYes maxStringMaximum version.Same as version.No recommendedStringRecommended version.Same as version.No • maintainers (required at least one) see PEAR_PackageFileManager::addMaintainer() for more info Table C.80: Parameters NameTypeDescriptionDefaultRequired handleStringUser identifier in channel.n/aYes nameStringReal name.n/aYes emailString n/aYes roleStringOne from: lead, developer, contributor or helper.n/aYes • replacements (optional) see PEAR_PackageFileManager::addReplacement() for more info Table C.81: Parameters NameTypeDescriptionDefaultRequired pathStringRelative path of file.n/aYes typeStringVariable type, either php-const, pear-config or package-info.n/aYes fromStringText to replace in the source file.n/aYes toStringVariable name to use for replacement.n/aYes • role See PEAR_PackageFileManager::addRole for more information. Available options: Table C.82: Parameters NameTypeDescriptionDefaultRequired extensionStringThe file extensionn/aYes roleStringThe file extensionn/aYes ## C.64 PharDataTask PharData archives 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. Table C.83: Attributes NameTypeDescriptionDefaultRequired basedirStringBase directory, which will be deleted from each included file (from path). Paths with deleted basedir part are local paths in archive.n/aYes destfileStringDestination (output) file. Will be recreated, if exists!n/aYes compressionStringCompression type (gzip, bzip2, none) to apply to the archive.noneNo ### C.64.1 Example Sample build command: <phardata destfile="./build/archive.tar" basedir="./" compression="gzip"> <fileset dir="./classes"> <include name="**/**" /> </fileset> </phardata> ### C.64.2 Supported Nested Tags • fileset ## C.65 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. Table C.84: Attributes NameTypeDescriptionDefaultRequired basedirStringBase directory, which will be deleted from each included file (from path). Paths with deleted basedir part are local paths in package.n/aYes destfileStringDestination (output) file. Will be recreated, if exists!n/aYes compressionStringCompression type (gzip, bzip2, none) to apply to the packed files.noneNo webstubStringRelative path within the phar package to run, if accessed through a web browser.n/aNo clistubStringRelative path within the phar package to run, if accessed on the command line.n/aNo stubStringA path to a php file that contains a custom stubn/aNo aliasStringAn alias to assign to the phar packagen/aNo signatureStringSignature algorithm (md5, sha1, sha256, sha512), used for this package.sha1No keyStringThe private key to sign the phar package with (PEM or PKCS#12 encoded)n/aNo keyPasswordStringThe password to use for the private keyn/aNo ### C.65.1 Example 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> ### C.65.2 Supported Nested Tags • fileset • metadata ## C.66 PhkPackageTask This task runs PHK_Creator.phk to build PHK-package. Learn more about build process in PHK Builder's Guide. Table C.85: Attributes NameTypeDescriptionDefaultRequired phkcreatorpathStringPath to PHK_Creator.phk.n/aYes inputdirectoryStringPath to directory, that will be packed.n/aYes outputfileStringOutput PHK-file. Directory, where file will be stored, must exist!n/aYes compressStringCompression type (gzip, bzip2, none) to apply to the packed files.noneNo stripBooleanWhen true, PHP source file(s) are stripped (filtered through php_strip_whitespace()) before being stored into the archive.falseNo nameStringThe package's name (Information only).n/aNo webrunscriptStringThe script to run in web direct access mode. Subfile path.n/aNo crccheckBooleanIf true, a CRC check will be forced every time the package is mounted.falseNo ### C.66.1 Example 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> <paentry>/</paentry> </webaccess> </phkpackage> ### C.66.2 Supported Nested Tags • webaccess Collection of path tags (see example below), that will be visible outside package in web mode. ## C.67 PhpCodeSnifferTask This task runs PHP_CodeSniffer to detect violations of a defined set of coding standards. Table C.86: Attributes NameTypeDescriptionDefaultRequired standardStringThe list of coding standards to test against. Separated by space, comma or semicolon.GenericNo formatStringThe output format. The full format is specified in the task itself. Additionally all report formats of PHP_CodeSniffer can be chosen (ex. checkstyle, full, summary, ...).fullNo Ignored if nested formatter elements are supplied. showSniffsBooleanPrint the list of used sniffs.falseNo showWarningsBooleanPrint warnings.trueNo showSourcesBooleanFlag that determines whether to show sources or not.trueNo propertyNameStringThe name of the property to set. This will be populated with the names of the sniff that were used.n/aNo docGeneratorStringThe name of the doc generator (HTML, Text).n/aNo docFileStringPath to write output file to. If not set documentation will be written to STDOUT when docGenerator is set.n/aNo fileStringThe file or folder to check (usually the nested tag fileset is used instead).falseEither this attribute or the nested tag fileset is required. sniffsStringThe list of allowed sniffs (separated by space, comma or semicolon). The sniffs must be part of the chosen standard.n/aNo verbosityIntegerThe verbosity level of CodeSniffer where level 1 prints progress information and level 2 prints developer debug information.0No encodingStringThe encoding of the files to checkiso-8859-1No tabWidthIntegerReplaces tabs with the given number of spaces. If zero no replacing is done.0No reportWidthIntegerThe max. width for the report.80No allowedFileExtensionsStringThe allowed file extensions / file types to process. Separated by space, comma or semicolon.php, inc, js, cssNo allowedTypesStringThe allowed types used by PHP_CodeSniffer::suggestType() which is used internally by some PHPCS rules (e.g. Squiz.Commenting.FunctionComment uses it to check variables / parameter types). Separated by space, comma or semicolon.n/a (PHP_CodeSniffer default is used)No ignorePatternsStringThe patterns to ignore files and folders (separated by space, comma or semicolon) when a directory is specified in the file attribute.n/aNo noSubdirectoriesBooleanDo not recurse into subdirectories when a directory is specified in the file attribute.falseNo haltonerrorBooleanStop the build process if errors occurred during the run.falseNo haltonwarningBooleanStop the build process if warnings occurred during the run.falseNo skipversioncheckBooleanSkips the version check when the task starts.falseNo cachefileStringIf set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely changenoneNo ### C.67.1 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="full" 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> Checks all files in the directory file matching the allowed file extension with the custom Foo standard and prints the summary report without warnings. <phpcodesniffer standard="Foo" format="summary" file="/path/to/source-files" allowedFileExtensions="php php5 inc"> <config name="installed_paths" value="/path/to/Standards/directory"/> </phpcodesniffer> ### C.67.2 Supported Nested Tags • fileset Either this nested tag or the attribute file is required. • config The configuration parameters which are usually loaded from the CodeSniffer.conf can be set. Table C.87: Attributes NameTypeDescriptionDefaultRequired nameStringName of the configuration parameter.n/aYes valueStringValue of the configuration parameter.n/aYes • formatter The results of the tests can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. Table C.88: Attributes NameTypeDescriptionDefaultRequired typeStringThe output format. Accepts the same values as the format attribute (default, xml, checkstyle, csv, report, summary & doc).n/aYes usefileBooleanBoolean that determines whether output should be sent to a file.trueNo outfileStringPath to write output file to.n/aYes, if usefile is true. ## C.68 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. NB: if you have installed the PHPCPD PHAR, make sure you set the pharlocation attribute! Table C.89: Attributes NameTypeDescriptionDefaultRequired fileStringPath to source file or pathn/aOnly when there are no nested fileset elements minTokensIntegerSets the minimum number of identical tokens (default: 70)70No minLinesIntegerSets the minimum number of identical lines (default: 5)5No formatStringThe format for the report when no nested formatter is used.defaultNo fuzzyBooleanIf fuzzy is set to true, the task will perform a fuzzy match.falseNo pharlocationStringLocation of the PHPCPD PHAR package.n/aNo ### C.68.1 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>

### C.68.2 Supported Nested Tags

• fileset

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

• formatter

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

Table C.90: Attributes

NameTypeDescriptionDefaultRequired
typeStringThe output format. Accepts the same values as the format attribute (default, pmd).n/aYes
useFileBooleanFlag that determines whether output should be sent to a file or not.trueNo
outfileStringPath to write output file to.n/aYes

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

NB: if you have installed the PHPLOC PHAR, make sure you set the pharlocation attribute!

Table C.91: Attributes

NameTypeDescriptionDefaultRequired
reportTypeStringThe type of the report. Available types are cli|csv|txt|xml.cliNo
reportNameStringThe name of the report type without a file extension.phploc-reportNo
reportDirectoryStringThe directory to write the report file to.falseYes, when report type csv, txt or xml is defined.
countTestsBooleanFlag to count the projects tests or not.falseNo
fileStringThe name of the file to check.n/aYes, when no nested fileset is defined.
suffixesStringA comma-separated list of file suffixes to check.phpNo
pharlocationStringLocation of the PHPLOC PHAR package.n/aNo

### C.69.1 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. ### C.69.2 Supported Nested Tags • fileset • formatter The results of the analysis can be printed in different formats. A formatter is required when reportType is not set. Table C.92: Attributes NameTypeDescriptionDefaultRequired typeStringThe output format. Accepts the same values as the reportType attribute (xml, csv, text, cli).n/aYes usefileBooleanBoolean that determines whether output should be sent to a file.trueNo outfileStringPath to write output file to.n/aYes ## C.70 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. NB: if you have installed the PHPMD Phar file, make sure you set the pharLocation attribute! Table C.93: Attributes NameTypeDescriptionDefaultRequired fileStringPath to source file or pathn/aOnly when there are no nested fileset elements rulesetsStringSets the rulesets used for analyzing the source codecodesize, unusedcodeNo minimumPriorityIntegerThe minimum priority for rules to load.5No allowedFileExtensionsStringComma-separated list of valid file extensions (without dot) for analyzed files.phpNo ignorePatternsStringComma-separated list of directory patterns to ignore..git, .svn, CVS, .bzr, .hgNo formatStringThe format for the report when no nested formatter is used.textNo pharlocationStringLocation of the PHPMD Phar file.n/aNo cachefileStringIf set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely changenoneNo ### C.70.1 Example <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.

### C.70.2 Supported Nested Tags

• fileset

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

• formatter

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

Table C.94: Attributes

NameTypeDescriptionDefaultRequired
typeStringThe output format. Accepts the same values as the format attribute (xml, html, text).n/aYes
usefileBooleanBoolean that determines whether output should be sent to a file.trueNo
outfileStringPath to write output file to.n/aYes

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

NB: if you have installed the PHP_Depend Phar file, make sure you set the pharLocation attribute!

Table C.95: Attributes

NameTypeDescriptionDefaultRequired
fileStringPath to source file or pathn/aOnly when there are no nested fileset elements
configFileStringPath to PHP_Depend configuration filen/aNo
allowedFileExtensionsStringComma-separated list of valid file extensions (without dot) for analyzed files.php,php5No
excludeDirectoriesStringComma-separated list of directory patterns to ignore..git, .svn, CVSNo
excludePackagesStringComma-separated list of packages to ignore.n/aNo
withoutAnnotationsBooleanShould the parse ignore doc comment annotations?falseNo
supportBadDocumentationBooleanShould PHP_Depend treat +global as a regular project package?falseNo
debugBooleanEnable debug output?falseNo
haltonerrorBooleanStop the build process if errors occurred during the run.falseNo
pharlocationStringLocation of the PHP_Depend Phar file.n/aNo

### C.71.1 Example

<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. ### C.71.2 Supported Nested Tags • fileset This nested tag is required when the file attribute is not set. • logger The results of the analysis can be parsed by differed loggers. At least one logger is required. Output will always be sent to a file. Table C.96: Attributes NameTypeDescriptionDefaultRequired typeStringThe name of the logger. Valid loggers are: jdepend-chart, jdepend-xml, overview-pyramid, phpunit-xml and summary-xml.n/aYes outfileStringPath to write output file to.n/aYes • analyzer Some additional analyzers can be added to the runner. Table C.97: Attributes NameTypeDescriptionDefaultRequired typeStringThe name of the analyzer. Valid analyzers are: coderank-mode.n/aYes valueStringThe value for the analyzer.n/aYes ## C.72 PhpDocumentorTask This task is now deprecated in favor of the Section C.73, “PhpDocumentor2Task”. This task runs phpDocumentor, an auto-documentation tool for PHP similar to Javadoc. Table C.98: Attributes NameTypeDescriptionDefaultRequired titleStringTitle for browser window / package index.n/aNo destdirStringDestination directory for output files.n/aYes targetStringAlias of destdir ("target" is config param used by PhpDocumentor)n/a outputStringOutput format (such as HTML:Smarty:PHP).n/aYes sourcecodeBooleanGenerate syntax-highlighted sourcecode file for each file parsed?falseNo examplesdirStringPath to directory in which to look for example documentation.n/aNo parseprivateBooleanParse @internal and elements marked private.falseNo javadocdescBooleanJavaDoc-compliant description parsing. Use on/off, default off (more flexibility)falseNo quietBooleanSuppress output to STDOUT.falseNo packageoutputStringOutput documentation only for selected packages. Use a comma-delimited listn/aNo ignoretagsStringComma-separated list of tags to ignore (@package, @subpackage, @access and @ignore may not be ignored).n/aNo defaultpackagenameStringname to use for the default package. If not specified, uses 'default'n/aNo defaultcategorynameStringname to use for the default category. If not specified, uses 'default'n/aNo pearBooleanTreat parse dirs as PEAR repository? (package is directory, _members are @access private)falseNo templatebaseStringSet base dirctory of all templates for this parse.n/aNo undocumentedelementsBooleanControl whether or not warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented.falseNo customtagsBooleanCustom tags, will be recognized and put in tags[] instead of unknowntags[].falseNo ignoreStringList of files to ignore, separated by ','.n/aNo ### C.72.1 Example <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> ### C.72.2 Supported Nested Tags • fileset - Files that should be included for parsing • projdocfileset - Files that should be treated as README/INSTALL/CHANGELOG files ## C.73 PhpDocumentor2Task This task runs phpDocumentor 2, a PHP 5.3-compatible API documentation tool. This project is the result of the merge of the phpDocumentor and DocBlox projects. Table C.99: Attributes NameTypeDescriptionDefaultRequired titleStringTitle of the project.n/aNo destdirStringDestination directory for output files.n/aYes quietBooleanDEPRECATEDn/aNo templateStringName of the documentation template to use.responsive-twigNo defaultPackageNameStringName of the default package.DefaultNo pharlocationStringLocation of the phpDocumentor PHAR package.n/aNo ### C.73.1 Example <phpdoc2 title="API Documentation" destdir="apidocs" template="responsive-twig"> <fileset dir="./classes"> <include name="**/*.php" /> </fileset> </phpdoc2> ### C.73.2 Supported Nested Tags • fileset - Files that should be included for parsing ## C.74 PhpDocumentorExternalTask This task is now deprecated in favor of the Section C.73, “PhpDocumentor2Task”. This is the same as the Section C.72, “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. Table C.100: Parameters NameTypeDescriptionDefaultRequired programpathStringPath to the phpdoc executable (relative or absolute).n/aNo sourcepathStringA directory to scan for parsable files. Supports multiple directories separated with a comma.n/aYes, if no <fileset> is given Table C.101: Unsupported Parameters NameDescription configdirCurrently 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. ### C.74.1 Example <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> ## C.75 PhpLintTask The PhpLintTask checks syntax (lint) on one or more PHP source code files. Table C.102: Attributes NameTypeDescriptionDefaultRequired fileStringPath to source filen/aNo haltonfailureBooleanStop the build process if the linting process encounters an error.falseNo errorpropertyStringThe name of a property that will be set to contain the error string (if any).n/aNo interpreterStringPath to alternative PHP interpreterDefaults to the ${php.interpreter} property which is the interpreter used to execute phing itself.No
cachefileStringIf set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely changenoneNo
levelStringControl the level at which phplint reports status messages. One of error, warning, info, verbose, debug.debugNo
tofileStringFile to write list of 'bad files' to.n/aNo
deprecatedAsErrorBooleanWhether to treat deprecated warnings (introduced in PHP 5.3) as errors.falseNo

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

### C.75.2 Supported Nested Tags

• fileset

## C.76 PHPUnitTask

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

NB: if you have installed the PHPUnit PHAR, make sure you set the pharlocation attribute!

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

Table C.103: Attributes

NameTypeDescriptionDefaultRequired
printsummaryBooleanPrint one-line statistics for each testcase.falseNo
bootstrapStringThe name of a bootstrap file that is run before executing the tests.noneNo
codecoverageBooleanGather code coverage information while running tests (requires Xdebug).falseNo
haltonerrorBooleanStop the build process if an error occurs during the test run.falseNo
haltonfailureBooleanStop the build process if a test fails (errors are considered failures as well).falseNo
haltonincompleteBooleanStop the build process if any incomplete tests are encountered.falseNo
haltonskippedBooleanStop the build process if any skipped tests are encountered.falseNo
failurepropertyStringName of property to set (to true) on failure.n/aNo
errorpropertyStringName of property to set (to true) on error.n/aNo
incompletepropertyStringName of property to set (to true) on incomplete tests.n/aNo
skippedpropertyStringName of property to set (to true) on skipped tests.n/aNo
usecustomerrorhandlerBooleanUse a custom Phing/PHPUnit error handler to process PHP errors.trueNo
processisolationBooleanEnable process isolation when executing tests.falseNo
configurationStringPath 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/aNo
groupsStringOnly run tests from the specified group(s).n/aNo
excludeGroupsStringExclude tests from the specified group(s).n/aNo
pharlocationStringLocation of the PHPUnit PHAR package.n/aNo

### C.76.1 Supported Nested Tags

• formatter

The results of the tests can be printed in different formats. Output will always be sent to a file, unless you set the usefile attribute to false. The name of the file is predetermined by the formatter and can be changed by the outfile attribute.

There are four predefined formatters - xml, clover, and crap4j print the test results in the JUnit, Clover, and Crap4J XML formats respectively. The plain formatter emits a short statistics line for all test cases. Custom formatters that implement phing.tasks.ext.phpunit.formatter.PHPUnitResultFormatter can be specified.

Table C.104: Attributes

NameTypeDescriptionDefaultRequired
typeStringUse a predefined formatter (either xml, plain, clover, crap4j, or summary).n/aOne of these is required.
classnameStringName of a custom formatter class.n/a
usefileBooleanBoolean that determines whether output should be sent to a file.trueNo
todirStringDirectory to write the file to.n/aNo
outfileStringFilename of the result.Depends on formatterNo

• batchtest

Define a number of tests based on pattern matching. batchtest collects the included files from any number of nested <fileset>s. It then generates a lists of classes that are (in)directly defined by each PHP file.

Table C.105: Attributes

NameTypeDescriptionDefaultRequired
excludeStringA list of classes to exclude from the pattern matching. For example, when you have two baseclasses BaseWebTest and BaseMathTest, which are included a number of testcases (and thus added to the list of testclasses), you can exclude those classes from the list by typing exclude="BaseWebTest BaseMathTest".n/aNo
classpathStringUsed to define more paths on which - besides the PHP include_path - to look for the test files.n/aNo
nameStringThe name that is used to create a testsuite from this batchtest.Phing BatchtestNo

### C.76.2 Example

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

### C.76.3 Supported Nested Tags

• fileset

## C.77 PHPUnitReport

This task transforms PHPUnit xml reports to HTML using XSLT.

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

Table C.106: Attributes

NameTypeDescriptionDefaultRequired
infileStringThe filename of the XML results file to use.testsuites.xmlNo
formatStringThe format of the generated report. Must be noframes or frames.noframesNo
styledirStringThe 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/aNo
todirStringAn existing directory where the files resulting from the transformation should be written to. Yes
usesorttableBooleanWhether to use the sorttable JavaScript library (see http://www.kryogenix.org/code/browser/sorttable/)falseNo

### C.77.1 Example

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

## C.78 PropertyRegexTask

Performs regular expression operations on an subject string, and sets the results to a property. There are two different operations that can be performed:

• Replace - The matched regular expression is replaced with a substitution pattern

• Match - Groupings within the regular expression are matched via a selection expression.

Table C.107: Attributes

NameTypeDescriptionDefaultRequired
propertyStringThe name of the property to set.n/aYes
overrideBooleanIf the property is already set, should we change it's value. Can be true or falsefalseNo
subjectStringThe subject to be processedn/aYes
patternStringThe regular expression pattern which is matched in the subject.n/aYes
matchStringA pattern which indicates what match pattern you want in the returned value. This uses the substitution pattern syntax to indicate where to insert groupings created as a result of the regular expression match.n/aYes (unless a replace is specified)
replaceStringA regular expression substitition pattern, which will be used to replace the given regular expression in the subject.n/aYes (unless a match is specified)
casesensitiveBooleanShould the match be case sensitivetrueNo
limitIntegerThe maximum possible replacements for each pattern in each subject string. Defaults to -1 (no limit).-1No
defaultValueIntegerThe value to set the output property to, if the subject string does not match the specific regular expression.n/aNo

### C.78.1 Match expressions

Expressions are matched in a the same syntax as a regular expression substitution pattern.

• $0 indicates the entire property name (default). •$1 indicates the first grouping

• $2 indicates the second grouping • etc... ### C.78.2 Replace It is important to note that when doing a "replace" operation, if the subject string does not match the regular expression, then the property is not set. You can change this behavior by supplying the "defaultValue" attribute. This attribute should contain the value to set the property to in this case. •$0 indicates the entire property name (default).

• $1 indicates the first grouping •$2 indicates the second grouping

• etc...

### C.78.3 Example

<propertyregex property="pack.name"
subject="package.ABC.name"
pattern="package\.([^.]*)\.name"
match="$1" casesensitive="false" defaultvalue="test1"/> <echo message="${pack.name}"/>

<propertyregex property="pack.name"
override="true"
subject="package.ABC.name"
pattern="(package)\.[^.]*\.(name)"
replace="$1.DEF.$2"
casesensitive="false"
defaultvalue="test2"/>

<echo message="${pack.name}"/> ## C.79 >ReplaceRegexpTask Replaces the occurrences of a given regular expression with a substitution pattern in a selected file or set of files. Table C.108: NameTypeDescriptionDefaultRequired fileStringFile to apply regular expression onn/aYes (or fileset) matchStringRegular expression match patternn/aYes (or pattern) patternStringRegular expression match patternn/aYes replaceStringThe replacement stringn/aYes ### C.79.1 Supported Nested Tags • fileset ## C.80 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 Table C.109: Attributes NameTypeDescriptionDefaultRequired fileStringrST input file to rendern/aYes (or fileset) formatString Output format: • html • latex • man • odt • s5 • xml htmlNo destinationStringPath to store the rendered file to. Used as directory if it ends with a /.magically determined from input fileNo uptodateBooleanOnly render if the input file is newer than the target filefalseNo toolpathStringPath to the rst2* tooldetermined from formatNo toolparamStringAdditional commandline parameters to the rst2* tooln/aNo modeIntegerThe mode to create directories with.From umaskNo ### C.80.1 Features • renders single files • render nested filesets • mappers to generate output file names based on the rst ones • multiple output formats • filter chains to e.g. replace variables after rendering • custom parameters to the rst2* tool • configurable rst tool path • uptodate check • automatically overwrites old files • automatically creates target directories ### C.80.2 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> ### C.80.3 Supported Nested Tags • fileset • mapper • filterchain ## C.81 S3PutTask Uploads an object to Amazon S3. This task requires the PEAR package Services_Amazon_S3 Table C.110: Attributes NameTypeDescriptionDefaultRequired keyStringAmazon S3 keyn/aYes (or defined before task call as: amazon.key) secretStringAmazon S3 secretn/aYes (or defined before task call as: amazon.secret) bucketStringBucket to store the object inn/aYes (or defined before task call as: amazon.bucket) contentStringContent to store in the objectn/aYes (or source or fileset) sourceStringWhere to read content for the object fromn/aYes (or content or fileset) objectStringObject namen/aYes (unless fileset) contentTypeStringContent type of the object, set to auto if you want to autodetect the content type based on the source file extensionbinary/octet-streamNo fileNameOnlyBooleanWhether filenames should contain paths when uploaded to a bucketfalseNo ### C.81.1 Example 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>

### C.81.2 Supported Nested Tags

• fileset

## C.82 S3GetTask

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

Table C.111: Attributes

NameTypeDescriptionDefaultRequired
keyStringAmazon S3 keyn/aYes (or defined before task call as: amazon.key)
secretStringAmazon S3 secretn/aYes (or defined before task call as: amazon.secret)
bucketStringBucket containing the objectn/aYes (or defined before task call as: amazon.bucket)
objectStringObject namen/aYes
targetStringWhere to store the object after downloadn/aYes

### C.82.1 Example

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

## C.83 SassTask

The SassTask converts SCSS or Sass files to CSS using either the 'sass' gem or the scssphp package.

Table C.112: Attributes

NameTypeDescriptionDefaultRequired
checkBooleanWhether to just check the syntax of the input files.FalseNo
compactBooleanSet the style to compact.FalseNo
compressedBooleanSet the style to compressed.FalseNo
crunchedBooleanSet the style to crunched. Supported by scssphp, not sass.FalseNo
expandBooleanSet the style to expanded.FalseNo
encodingStringDefault encoding for input files. Supported by scssphp.utf-8No
executableStringLocation/name of the sass executable, if required.sassNo
extfilterStringExtension to filter against.n/aNo
failonerrorBooleanWhether to fail/halt if an error occurs.FalseNo
fileStringName of single file to process.N/ANo
flagsStringAdditional flags to set for sass executable.n/aNo
inputStringName of single file to process. Synonym for file.N/ANo
keepsubdirectoriesBooleanWhether to keep the directory structure when compiling.TrueNo
linenumbersBooleanWhether to annotate generated CSS with source file and line numbers.FalseNo
nestedBooleanSet the style to expanded.trueNo
newextStringExtension for newly created files.cssNo
nocacheBooleanWhether to cache parsed sass files.n/aNo
outputStringCorresponding output file for 'file'/'input' parameter. If not specified and outputpath is, then the generated file is placed there, with the filename based on the input file. If neither is specified, then the generated file is placed into the directory that the input file is in. N/ANo
outputpathStringWhere to place the generated CSS files.n/aYes
pathStringSpecify sass import path. e.g. --load-path ...n/aNo
removeoldextBooleanWhether to strip existing extension off the output filename.TrueNo
styleStringName of style to output. Must be one of 'nested', 'compact', 'compressed', 'crunched' or 'expanded'. 'Helper' attributes may also be used. 'crunched' is supported by scssphp only.nestedNo
traceBooleanWhether to show a full stack trace on error.FalseNo
unixnewlinesBooleanUse Unix-style newlines in written files.TrueNo
useSassBooleanWhether to use the 'sass' command line tool. Takes precedence over scssphp if both are available and enabled.TrueNo
useScssphpBooleanWhether to use the 'scssphp' PHP package.TrueNo

The useSass and useScssphp attributes can be used to indicate which compiler should be used, which would be useful if both are available. If both are available and enabled, then the 'sass' compiler is used rather than the scssphp library.

<sass style="compact" trace="yes" unixnewlines="yes" outputpath="${compiled.dir.resolved}"> <fileset dir="."/> </sass> ### C.83.2 Supported Nested Tags • fileset ## C.84 ScpTask The ScpTask copies files to and from a remote host using scp. This task requires the PHP SSH2 extension to function. Table C.113: Attributes NameTypeDescriptionDefaultRequired hostStringRemote hostnoneYes portIntegerRemote port22No usernameStringUsername to use for the connectionnoneYes passwordStringPassword to use for the connectionnoneNo pubkeyfileStringPublic key file (OpenSSH format) to use for the connectionnoneNo privkeyfileStringPrivate key file (OpenSSH format) to use for the connectionnoneNo privkeyfilepassphraseStringPrivate key file passphrase to use for the connectionnoneNo autocreateBooleanWhether to autocreate remote directoriestrueNo todirStringDirectory to put file(s) innoneNo fileStringFilename to usenoneNo fetchBooleanWhether to fetch (instead of copy to) the filefalseNo levelStringControl the level at which the task reports status messages. One of error, warning, info, verbose, debug.verboseNo ### C.84.1 Example <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. ### C.84.2 Supported Nested Tags • fileset • sshconfig Sometimes it is necessary to set specific configuration parameters on the ssh connection when connecting to a remote server. You can set them with the sshconfig nested tag. Set the parameters to specify connection and encryption options. These are the parameters as specified by the$methods parameter of the ssh2_connect function. See ssh2_connect for more information

sshconfig can also be used as project level parameter with a refid so the same parameters can be re-used across a project easily.

Table C.114: Attributes

NameTypeDescriptionDefaultRequired
kexStringList of key exchange methods to advertise, comma separated in order of preference.n/aNo
hostkeyStringList of hostkey methods to advertise, come separated in order of preference.n/aNo
clientNested TagElement containing attributes crypt, comp, and mac method preferences for messages sent from client to server. All attributes are optional.n/aNo
serverNested TagElement containing attributes crypt, comp, and mac method preferences for messages sent from server to client. All attributes are optional.n/aNo

## C.85 SmartyTask

A task for generating output by using Smarty.

Table C.115: Attributes

NameTypeDescriptionDefaultRequired
controlTemplateStringThe control template used to generate the output.noneYes
templatePathStringThe path where Smarty will look for templates.noneYes
outputDirectoryStringThe output directory, will be created if it doesn't exist.noneYes
compilePathStringThe path Smarty uses as a "cache" for compiled templates.noneNo
forceCompileBooleanWhether Smarty should always recompile templates.falseNo
configPathStringThe path where Smarty will look for config files.noneNo
leftDelimiterStringThe template left delimiter.noneNo
rightDelimiterStringThe template right delimiter.noneNo
contextPropertiesStringThe path to a property file that will be fed into the initial template context.noneNo

## C.86 SshTask

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

Table C.116: Attributes

NameTypeDescriptionDefaultRequired
hostStringRemote hostnoneYes
portIntegerRemote port22No
usernameStringUsername to use for the connectionnoneYes
passwordStringPassword to use for the connectionnoneNo
pubkeyfileStringPublic key file (OpenSSH format) to use for the connectionnoneNo
privkeyfileStringPrivate key file (OpenSSH format) to use for the connectionnoneNo
privkeyfilepassphraseStringPrivate key file passphrase to use for the connectionnoneNo
commandStringCommand to execute on the remote servernoneYes
propertyStringThe name of the property to capture (any) output of the commandnoneNo
displayBooleanWhether to display the output of the commandtrueNo
ptyStringThe terminal type to opennoneNo
failonerrorBooleanDecides if a command chain will fail if one of the executed commands failed. Added for backward compatibility. Set to true if you execute more than one command and want the task to fail on any error.FalseNo

### C.86.1 Example

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

Executes a single command on the remote server.

### C.86.2 Supported Nested Tags

• sshconfig

## C.90 SvnCopyTask

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

Table C.122: Attributes

NameTypeDescriptionDefaultRequired
messageStringLog messagen/aNo
svnpathStringPath to Subversion binary/usr/bin/svnNo
repositoryurlStringURL of SVN repositorynoneYes
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
forceBooleanForce overwrite files if they already existfalseNo
nocacheBooleanConnection credentials will not be cachedfalseNo
todirStringPath to export tononeYes
depthStringLimit operation by depthempty, files, immediates or infinityNo
trustServerCertBooleanTrust self-signed certificatesfalseNo

### C.90.1 Example

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

## C.91 SvnExportTask

The SvnExportTask exports a Subversion repository to a local directory.

Table C.123: Attributes

NameTypeDescriptionDefaultRequired
revisionStringRevision to use in exportHEADNo
svnpathStringPath to Subversion binary/usr/bin/svnNo
repositoryurlStringURL of SVN repositorynoneYes
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
nocacheBooleanConnection credentials will not be cachedfalseNo
todirStringPath to export tononeYes
depthStringLimit operation by depthempty, files, immediates or infinityNo
ignoreexternalsBooleanIgnore externals definitionsfalseNo
trustServerCertBooleanTrust self-signed certificatesfalseNo

### C.91.1 Example

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

## C.92 SvnInfoTask

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

Table C.124: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
workingcopyStringWorking copy directorynoneYes, or repositoryurl
repositoryurlStringURL of remote repositorynoneYes, or workingcopy
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
propertynameStringName of property to usesvn.infoNo
elementStringSets whether to store actual last changed revision of the directory/file mentionedurlNo
subelementStringSets whether to force compatibility with older SVN versions (< 1.2)noneNo

### C.92.1 Example

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

## C.93 SvnLastRevisionTask

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

Table C.125: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
workingcopyStringWorking copy directorynoneYes, or repositoryurl
repositoryurlStringURL of remote repositorynoneYes, or workingcopy
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
propertynameStringName of property to usesvn.lastrevisionNo
lastChangedBooleanSets whether to store actual last changed revision of the directory/file mentionedfalseNo
forceCompatibleBooleanDeprecated: Sets whether to force compatibility with older SVN versions (< 1.2)falseNo

### C.93.1 Example

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

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

Table C.126: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
workingcopyStringWorking copy directorynoneOne of the two
repositoryurlStringURL of remote repositorynone
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
propertynameStringName of property to usesvn.listNo
forceCompatibleBooleanDeprecated: Sets whether to force compatibility with older SVN versions (< 1.2)trueNo
limitIntegerLimits the number of items to get back from the commandn/aNo
orderDescendingBooleanSets whether to reverse the order of the listed itemsfalseNo

### C.94.1 Example

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

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

Table C.127: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
workingcopyStringWorking copy directorynoneOne of the two
repositoryurlStringURL of remote repositorynone
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
propertynameStringName of property to usesvn.listNo
forceCompatibleBooleanDeprecated: Sets whether to force compatibility with older SVN versions (< 1.2)trueNo
limitIntegerLimits the number of items to get back from the commandn/aNo

### C.95.1 Example

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