# Phing User Guide

2016-12-27

Preface
1.1. Authors
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.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.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
B.7. Basename
B.13. Diagnostics
B.14. Dirname
B.27. PathConvert
B.30. Phingversion
B.34. Record
B.37. Retry
C.75. PHPUnitReport
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.2. ExpandProperties
E.3. ConcatFilter
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.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.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

## 1.1 Authors

• Alex Black, enigma@turingstudio.com

• Manuel Holtgrewe, grin@gmx.net

• Hans Lellelid, hans@xmpl.org

• Michiel Rook, mrook@php.net

• Ken Guest, ken@linux.ie

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
html         Builds the HTML version
htmlfancy    Builds the HTML version with an alternative styling for screen output
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"
version="5.0"
...
</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">
...
</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). • 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 ### 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 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 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 add them 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.

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

<param name="lines" value="10"/>
</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"> <param type="token" name="BC_PATH" value="${top.builddir}/"/>
<param type="token" name="BC_PATH"
value="${top.builddir}/testsite/user/${lang}/"/>
</filterreader>

As the pipe concept in Unix, the filter concept is quite complex but powerful. To get a better understanding of different filters and how they can be used, take a look at any of the many uses of FilterChains in the build files for the binarycloud Bibliography project.

### 5.7.4 File Mappers

With FilterChains and filters provide a powerful tool for changing contents of files, mappers provide a powerful tool for changing the names of files.

To use a Mapper, you must specify a pattern to match on and a replacement pattern that describes how the matched pattern should be transformed. The simplest form is basically no different from the DOS copy command:

copy *.bat *.txt

In Phing this is the glob Mapper:

<mapper type="glob" from="*.bat" to="*.txt"/>

Phing also provides support for more complex mapping using regular expressions:

<mapper type="regexp" from="^(.*)\.conf\.xml$$" to="\1.php"/> Consider the example below to see how Mappers can be used in a build file. This example includes some of the other concepts introduced in this chapter, such as FilterChains and FileSets. If you don't understand everything, don't worry. The important point is that Mappers are types too, which can be used in tasks that support them. <copy> <fileset dir="."> <include name="*.ent.xml"/> </fileset> <mapper type="regexp" from="^(.*)\.ent\.xml" to="\1.php"/> <filterchain> <filterreader classname="phing.filters.XsltFilter"> <param name="style" value="ent2php.xsl"/> </filterreader> </filterchain> </copy> For a complete reference, see Appendix D, Core Types ## 5.8 Conditions Conditions are nested elements of the condition, if and waitfor tasks. ### 5.8.1 not The <not> element expects exactly one other condition to be nested into this element, negating the result of the condition. It doesn't have any attributes and accepts all nested elements of the condition task as nested elements as well. ### 5.8.2 and The <and> element doesn't have any attributes and accepts an arbitrary number of conditions as nested elements. This condition is true if all of its contained conditions are, conditions will be evaluated in the order they have been specified in the build file. The <and> condition has the same shortcut semantics as the && operator in some programming languages, as soon as one of the nested conditions is false, no other condition will be evaluated. ### 5.8.3 or The <or> element doesn't have any attributes and accepts an arbitrary number of conditions as nested elements. This condition is true if at least one of its contained conditions is, conditions will be evaluated in the order they have been specified in the build file. The <or> condition has the same shortcut semantics as the || operator in some programming languages, as soon as one of the nested conditions is true, no other condition will be evaluated. ### 5.8.4 xor The <xor> element performs an exclusive or on all nested elements, similar to the ^ operator in PHP. It only evaluates to true if an odd number of nested conditions are true. There is no shortcutting of evaluation, unlike the <and> and <or> tests. It doesn't have any attributes and accepts all nested elements of the condition task as nested elements as well. ### 5.8.5 os Test whether the current operating system is of a given type. Table 5.1: OS Attributes AttributeDescriptionRequired familyThe name of the operating system family to expect.Yes Supported values for the family attribute are: • windows (for all versions of Microsoft Windows) • mac (for all Apple Macintosh systems) • unix (for all Unix and Unix-like operating systems) Note: machines running OSX match on the mac and unix families! To test for Macs that don't run a Unix-like OS, use the following code: <condition property="isMacOsButNotMacOsX"> <and> <os family="mac"/> <not> <os family="unix"/> </not> </and> </condition> ### 5.8.6 equals Tests whether the two given Strings are identical Table 5.2: equals Attributes AttributeDescriptionRequired arg1First string to test.Yes arg2Second string to test.Yes casesensitivePerform a case sensitive comparison. Default is true.No trimTrim whitespace from arguments before comparing them. Default is false.No ### 5.8.7 versioncompare Compares two given versions Table 5.3: versioncompare Attributes AttributeDescriptionRequired versionThe version you want to compareYes desiredVersionThe version you want to compare againstYes operatorThe operator to use for version comparison. Default is >=.No debugTurns on debug mode, that echoes the comparion message. Default is false.No <versioncompare version="{aProperty}" desiredVersion="1.3" operator="gt" /> This condition internally uses PHP version_compare(). Operators and behavior are the same. ### 5.8.8 http Condition to wait for a HTTP request to succeed. Attributes are: • url - the URL of the request. • errorsBeginAt - number at which errors begin at. • quiet - Set quiet mode, which suppresses warnings and errors. Table 5.4: http Attributes AttributeDescriptionRequired urlThe URL of the request.Yes errorsBeginAtNumber at which errors begin at. - Default: 400No quietSet quiet mode, which suppresses warnings and errors. Default is falseNo <http url="http://url.to.test" errorsBeginAt="404" /> ### 5.8.9 socket Condition to test for a (tcp) listener on a specified host and port. Table 5.5: socket Attributes AttributeDescriptionRequired serverThe hostname or ip address of the server.Yes portThe port number of the server.Yes <socket server="localhost" port="80" /> ### 5.8.10 hasfreespace Condition returns true if selected partition has the requested space, false otherwise. Table 5.6: hasfreespace Attributes AttributeDescriptionRequired partitionThe partition/device to check.Yes neededThe amount of free space required.Yes <hasfreespace partition="c:" needed="10M" /> This condition internally uses PHP disk_free_space(). ### 5.8.11 isset Test whether a given property has been set in this project. Table 5.7: isset Attributes AttributeDescriptionRequired propertyThe name of the property to test.Yes ### 5.8.12 contains Tests whether a string contains another one. Table 5.8: contains Attributes AttributeDescriptionRequired stringThe string to search in.Yes substringThe string to search for.Yes casesensitivePerform a case sensitive comparison. Default is true.No ### 5.8.13 istrue Tests whether a string evaluates to true. Table 5.9: istrue Attributes AttributeDescriptionRequired valuevalue to testYes <istrue value="{someproperty}"/> <istrue value="false"/> ### 5.8.14 isfalse Tests whether a string evaluates to not true, the negation of <istrue> Table 5.10: isfalse Attributes AttributeDescriptionRequired valuevalue to testYes <isfalse value="{someproperty}"/> <isfalse value="false"/> ### 5.8.15 ispropertytrue Tests whether a property evaluates to true. Table 5.11: ispropertytrue Attributes AttributeDescriptionRequired propertyproperty to testYes <ispropertytrue name="someproperty"/> ### 5.8.16 ispropertyfalse Tests whether a property evaluates to not true, the negation of <ispropertytrue> Table 5.12: ispropertyfalse Attributes AttributeDescriptionRequired propertyproperty name to testYes <ispropertyfalse name="someproperty"/> ### 5.8.17 referenceexists Tests whether a specified reference exists. Table 5.13: referenceexists Attributes AttributeDescriptionRequired refreference to test forYes <referenceexists ref="{someid}"/> ### 5.8.18 available This condition is identical to the Available task, all attributes and nested elements of that task are supported, the property and value attributes are redundant and will be ignored. ### 5.8.19 filesmatch Test two files for matching. Nonexistence of one file results in "false", although if neither exists they are considered equal in terms of content. This test does a byte for byte comparison, so test time scales with byte size. NB: if the files are different sizes, one of them is missing or the filenames match the answer is so obvious the detailed test is omitted. Table 5.14: filesmatch Attributes AttributeDescriptionRequired file1First file to test.Yes file2Second file to test.Yes <filesmatch file1="{file1}" file2="{file2}"/> ### 5.8.20 isfileselected Test whether a file passes an embedded selector. Table 5.15: isfileselected Attributes AttributeDescriptionRequired fileThe file to check if is passes the embedded selector.Yes basedirThe base directory to use for name based selectors. It this is not set, the project's basedirectory will be used.No <isfileselected file="a.xml"> <date datetime="06/28/2000 2:02 pm" when="equal"/> </isfileselected> ### 5.8.21 isfailure Test the return code of an executable for failure. Table 5.16: isfailure Attributes AttributeDescriptionRequired codeThe return code to test.Yes <exec command="test" returnProperty="return.code"/> <if> <isfailure code="{return.code}"/> <then><echo msg="{return.code}"/></then> </if> ### 5.8.22 matches Test if the specified string matches the specified regular expression pattern. Table 5.17: matches Attributes AttributeDescriptionRequired stringThe string to test.Yes patternThe regular expression pattern used to test.Yes casesensitivePerform a case sensitive match. Default is true.No multilinePerform a multi line match. Default is false.No modifiersThe regular expression modifiers used to test.No # Chapter 6 Extending Phing Phing was designed to be flexible and easily extensible. Phing's existing core and optional tasks do provide a great deal of flexibility in processing files, performing database actions, and even getting user feedback during a build process. In some cases, however, the existing tasks just won't suffice and because of Phing's open, modular architecture adding exactly the functionality you need is often quite trivial. In this chapter we'll look primarily at how to create your own tasks, since that is probably the most useful way to extend Phing. We'll also give some more information about Phing's design and inner workings. ## 6.1 Extension Possibilities There are three main areas where Phing can be extended: Tasks, Types, Mappers. The following sections discuss these options. ### 6.1.1 Tasks Tasks are pieces of codes that perform an atomic action like installing a file. Therefore a special worker class hast to be created and stored in a specific location, that actually implements the job. The worker is just the interface to Phing that must fulfill some requirements discussed later in this chapter, however it can - but not necessarily must - use other classes, workers and libraries that aid performing the operations needed. ### 6.1.2 Types Extending types is a rare need; nevertheless, you can do it. A possible type you might implement is urlset, for example. You may end up needing a new type for a task you write; for example, if you were writing the XSLTTask you might discover that you needed a special type for XSLTParams (even though in that case you could probably use the generic name/value Parameter type). In cases where the type is really only for a single task, you may want to just define the type class in the same file as the Task class, rather than creating an official stand-alone Type. ### 6.1.3 Mappers Creating new mappers is also a rare need, since most everything can be handled by the Appendix F, Core mappers. The Mapper framework does provide a simple way for defining your own mappers to use instead, however, and mappers implement a very simple interface. ## 6.2 Source Layout ### 6.2.1 Files And Directories Before you are going to start to extend Phing let's have a look at the source layout. You should be comfortable with the organization of files witch in the source tree of Phing before start coding. After you extracted the source distribution or checked it out from git you should see the following directory structure: PHING_HOME |-- bin |-- classes | -- phing | |-- filters | | -- util | |-- mappers | |-- parser | |-- tasks | | |-- ext | | |-- system | | | -- condition | | -- user | -- types |-- docs | -- phing_guide -- test |-- classes -- etc The following table briefly describes the contents of the major directories: Table 6.1: Phing source tree directories DirectoryContents bin The basic applications (phing, configure) as well as the wrapper scripts for different platforms (currently Unix and Windows). classes Repository of all the classes used by Phing. This is the base directory that should be on the PHP include_path. In this directory you will find the subdirectory phing/ with all the Phing relevant classes. docs Documentation files. Generated books, online manuals as well as the PHPDoc generated API documentation. test A set of testcases for different tasks, mappers and types. If you are developing in git you should add a testcase for each implementation you check in. Currently there is no distinction between the source layout and the build layout of Phing. The directory layout shows the file tree that carries some additional files like the Phing website. Later on there may be a buildfile to create a clean distribution tree of Phing itself. ### 6.2.2 File Naming Conventions There are some file naming conventions used by Phing. Here's a quick rundown on the most basic conventions. A more detailed list can be found in [See Naming And Coding Standards]: • Filenames consist of no more or less than two elements: name and extension . • Choose short descriptive filenames (must be less than 31 chars) • Names must not contain dots. • Files containing PHP code must end with the extension .php . • There must be only one class per file (no procedural methods allowed, use a separate file for them), with the exception of "inner"-type / helper classes that can be declared in the same file as the "outer" / main class. • The name portion of the file must be named exactly like the class it contains. • Buildfiles and configure rulesets must end with the extension .xml . ### 6.2.3 Coding Standards We are using PEAR coding standards. We are using a less strict version of these standards, but we do insist that new contributions have phpdoc comments and make explicitly declarations about public/protected/private variables and methods. If you have suggestions about improvements to Phing codebase, don't hesitate to let us know. ## 6.3 System Initialization PHP installations are typically quite customized -- e.g. different memory_limit, execution timeout values, etc. The first thing that Phing does is modify PHP INI variables to create a standard PHP environment. This is performed by the init layer of Phing that uses a three-level initialization procedure. It basically consists of three different files: • Platform specific wrapper scripts in bin/ • Main application in bin/ • Phing class in classes/phing/ At the first look this may seem to be unnecessary overhead. Why three levels of initialization? The main reason why there are several entry points is that Phing is build so that other frontends (e.g. PHP-GTK) could be used in place of the command line. ### 6.3.1 Wrapper Scripts This scripts are technical not required but provided for the ease of use. Imagine you have to type every time you want to build your project: php -qC /path/to/phing/bin/phing.php -verbose all distro snapshot Indeed that is not very elegant. Furthermore if you are lax in setting your environment variables these script can guess the proper variables for you. However you should always set them. The scripts are platform dependent, so you will find shell scripts for Unix like platforms (sh) as well as the batch scripts for Windows platforms. If you set-up your path properly you can call Phing everywhere in your system with this command-line (referring to the above example): phing -v2 all distro ### 6.3.2 The Main Application (phing.php) This is basically a wrapper for the Phing class that actually does all the logic for you. If you look at the source code for phing.php you will see that all real initialization is handled in the Phing class. phing.php is simply the command line entry point for Phing. ### 6.3.3 The Phing Class Given that all the prior initialization steps passed successfully the Phing is included and Phing::startup() is invoked by the main application script. It sets-up the system components, system constants ini-settings, PEAR and some other stuff. The detailed start-up process is as follows: • Start Timer • Set System Constants • Set Ini-Settings • Set Include Paths After the main application completed all operations (successfully or unsuccessfully) it calls Phing::shutdown(EXIT_CODE) that takes care of a proper destruction of all objects and a gracefully termination of the program by returning an exit code for shell usage (see [See Program Exit Codes] for a list of exit codes). ## 6.4 System Services ### 6.4.1 The Exception system Phing uses the PHP5 try/catch/throw Exception system. Phing defines a number of Exception subclasses for more fine-grained handling of Exceptions. Low level Exceptions that cannot be handled will be wrapped in a BuildException and caught by the outer-most catch() {} block. ## 6.5 Build Lifecycle This section exists to explain -- or try -- how Phing "works". Particularly, how Phing proceeds through a build file and invokes tasks and types based on the tags that it encounters. ### 6.5.1 How Phing Parses Buildfiles Phing uses an ExpatParser class and PHP's native expat XML functions to handle the parsing of build files. The handler classes all extend the phing.parser.AbstractHandler class. These handler classes "handle" the tags that are found in the buildfile. Core tasks and datatypes are mapped to XML tag names in the defaults.properties files -- specifically phing/tasks/defaults.properties and phing/types/defaults.properties. It works roughly like this: 1. phing.parser.RootHandler is registered to handle the buildfile XML document 2. RootHanlder expects to find exactly one element: <project>. RootHandler invokes the ProjectHandler with the attributes from the <project> tag or throws an exception if no <project> is found, or if something else is found instead. 3. ProjectHandler expects to find <target> tags; for these ProjectHandler invokes the TargetHandler. ProjectHandler also has exceptions for handling certain tasks that can be performed at the top-level: <resolve>, <taskdef>, <typedef>, and <property>; for these ProjectHandler invokes the TaskHandler class. If a tag is presented that doesn't match any expected tags, then ProjectHandler assumes it is a datatype and invokes the DataTypeHandler. 4. TargetHandler expects all tags to be either tasks or datatypes and invokes the appropriate handler (based on the mappings provided in the defaults.properties files). 5. Tasks and datatypes can have nested elements, but only if they correspond to a create*() method in the task or datatype class. E.g. a nested <param> tag must correspond to a createParam() method of the task or datatype. ... More to come ... ## 6.6 Writing Tasks ### 6.6.1 Creating A Task We will start creating a rather simple task which basically does nothing more than echo a message to the screen. See [below] for the source code and the following [below] for the XML definition that is used for this task. <?php require_once "phing/Task.php"; class MyEchoTask extends Task { /** * The message passed in the buildfile. */ private message = null; /** * The setter for the attribute "message" */ public function setMessage(str) { this->message = str; } /** * The init method: Do init steps. */ public function init() { // nothing to do here } /** * The main entry point method. */ public function main() { print(this->message); } } ?> This code contains a rather simple, but complete Phing task. It is assumed that the file is named MyEchoTask.php. For this example, we're assuming that the file is placed in /home/example/classes. We'll explain the source code in detail shortly. But first we'd like to discuss how we should register the task to Phing so that it can be executed during the build process. ### 6.6.2 Using the Task The task shown [above] must somehow get loaded and called by Phing. Therefore it must be made available to Phing so that the buildfile parser is aware a correlating XML element and it's parameters. Have a look at the minimalistic buildfile example given in [the buildfile below] that does exactly this. <?xml version="1.0" ?> <project name="test" basedir="." default="test.myecho"> <includepath classpath="/home/example/classes" /> <taskdef name="myecho" classname="MyEchoTask" /> <target name="test.myecho"> <myecho message="Hello World" /> </target> </project> To register the custom task with Phing, the taskdef element (line 5) is used. See Section B.40, “TaskdefTask ” for a more detailed explanation. Optionally, before the taskdef element, the includepath element adds a path to PHP's include path. This is of course only required if the mentioned path isn't already on the include path. See Section B.22, “IncludePathTask ” for a more detailed explanation. Now, as we have registered the task by assigning a name and the worker class ([see source code above]) it is ready for usage within the <target> context (line 8). You see that we pass the message that our task should echo to the screen via an XML attribute called "message". ### 6.6.3 Source Discussion Now that you've got the knowledge to execute the task in a buildfile it's time to discuss how everything works. ### 6.6.4 Task Structure All files containing the definition of a task class follow a common well formed structure: • Include/require statements to import all required classes • The class declaration and definition • The class's properties • The class's constructor • Setter methods for each XML attribute • The init() method • The main() method • Arbitrary private (or protected) class methods ### 6.6.5 Includes Always include/require all the classes needed for this task in full written notation. Furthermore you should always include phing/Task.php at the very top of your include block. Then include all other required system or proprietary classes. ### 6.6.6 Class Declaration If you look at line 5 in [the source code of the task] you will find the class declaration. This will be familiar to you if you are experienced with OOP in PHP (we assume here that you are). Furthermore there are some fine-grained rules you must obey when creating the classes (see also,[naming and coding standards]): • Your classname must be exactly like the taskname you are going to implement plus the suffix "Task". In our example case the classname is MyEchoTask (constructed by the taskname "myecho" plus the suffix "task"). The upper/lower case casing is currently only for better reading. However, it is encouraged that you use it this way. • The task class you are creating must at least extend "Task" to inherit all task specific methods. ### 6.6.7 Class Properties The next lines you are coding are class properties. Most of them are inherited from the Task superclass, so there's not need to redeclare them. Nevertheless you should declare the following ones by your own: • Taskname. Always hard code the taskname property that equals the name of the XML element that your task claims. Currently this information is not used - but it will be in the future. • Your arbitrary properties that reflect the XML attributes/elements which your task accepts. In the MyEchoTask example the coded properties can be found in lines 7 to 11. Give you properties meaningful descriptive names that clearly state their function within the context. A couple of properties are inherited from the superclass that must not be declared in the properties part of the code. For a list of inherited properties (most of them are reserved, so be sure not to overwrite them with your own) can be found in the "Phing API Reference" in the docs/api/ directory. ### 6.6.8 The Constructor The next block that follows is the class's constructor. It must be present and call at least the constructor or the parent class. Of course, you can add some initialization data here. It is recommended that you define your prior declared properties here. ### 6.6.9 Setter Methods As you can see in the XML definition of our task ([see buildfile above] , line 9) there is an attribute defined with the task itself, namely "message" with a value of the text string that our task should echo. The task must somehow become aware of the attribute name and the value. Therefore the setter methods exist. For each attribute you want to import to the task's namespace you have to define a method named exactly after the very attribute plus the string "set" prepended. This method accepts exactly one parameter that holds the value of the attribute. Now you can set the a class internal property to the value that is passed via the setter method. In the setter method you should also perform any casting operations and/or check if the attribute value is a valid value. If this is not the case, throw a BuildException. In some cases, such as when you have three attributes and at least one of them should be set, you may want to check the attribute values inside the init() or main() method. In out example the setter is named setMessage , because the XML attribute the echo task accepts is "message". setMessage now takes the string "Hello World" provided by the parser and sets the value of the internal class property strMessage to "Hello World". It is now available to the task for further disposal. ### 6.6.10 Creator Methods Creator methods allow you to manage nested XML tags in your new Phing Task. For example, you might be developing a task that would contain a nested "color" XML tag. In this instance a creator method named createcolor would be required. <tag> <color red="..." green="..." blue="..."> </tag>  If the XML for the task and the subtag look like the above, the PHP code for it could look something like the following: class TagTask extends Task { protected colors = array(); public function createColor() { colorObj = new TagColor(); this->colors[] = colorObj; return colorObj; } } class TagColor { public function setRed(value) { } public function setGreen(value) { } public function setBlue(value) { } } ### 6.6.11 init() Method The init method gets called when the <taskname> xml element closes. It must be implemented even if it does nothing like in the example above. You can do init steps here required to setup your task object properly. After calling the Init-Method the task object remains untouched by the parser. Init should not perform operations related somehow to the action the task performs. An example of using init may be cleaning up the strMessage variable in our example (i.e. trim(strMessage)) or importing additional workers needed for this task. The init method should return true or an error object evaluated by the governing logic. If you don't implement init method, phing will shout down with a fatal error. ### 6.6.12 main() Method There is exactly one entry point to execute the task. It is called after the complete buildfile has been parsed and all targets and tasks have been scheduled for execution. From this point forward the very implementation of the tasks action starts. In case of our example a message (imported by the proper setter method) is Logged to the screen through the system's "Logger" service (the very action this task is written for). The Log() method-call in this case accepts two parameters: a event constant and the message to log. ### 6.6.13 Arbitrary Methods For the more or less simple cases (as our example) all the logic of the task is coded in the Main() method. However for more complex tasks common sense dictates that particular action should be swapped to smaller, logically contained units of code. The most common way to do this is separating logic into private class methods - and in even more complex tasks in separate libraries. private function myPrivateMethod() { // definition } ## 6.7 Writing Types You should only create a standalone Type if the Type needs to be shared by more than one Task. If the Type is only needed for a specific Task -- for example to handle a special parameter or other tag needed for that Task -- then the Type class should just be defined within the same file as the Task. (For example, phing/filters/XSLTFilter.php also includes an XSLTParam class that is not used anywhere else.) For cases where you do need a more generic Type defined, you can create your own Type class -- similar to the way a Task is created. ### 6.7.1 Creating a DataType Type classes need to extend the abstract DataType class. Besides providing a means of categorizing types, the DataType class provides the methods necessary to support the "refid" attribute. (All types can be given an id, and can be referred to later using that id.) In this example we are creating a DSN type because we have written a number of DB-related Tasks, each of which need to know how to connect to the database; instead of having database parameters for each task, we've created a DSN type so that we can identify the connection parameters once and then use it in all our db Tasks. require_once "phing/types/DataType.php"; /** * This Type represents a DB Connection. */ class DSN extends DataType { private url; private username; private password; private persistent = false; /** * Sets the URL part: mysql://localhost/mydatabase */ public function setUrl(url) { this->url = url; } /** * Sets username to use in connection. */ public function setUsername(username) { this->username = username; } /** * Sets password to use in connection. */ public function setPassword(password) { this->password = password; } /** * Set whether to use persistent connection. * @param boolean persist */ public function setPersistent(persist) { this->persistent = (boolean) persist; } public function getUrl(Project p) { if (this->isReference()) { return this->getRef(p)->getUrl(p); } return this->url; } public function getUsername(Project p) { if (this->isReference()) { return this->getRef(p)->getUsername(p); } return this->username; } public function getPassword(Project p) { if (this->isReference()) { return this->getRef(p)->getPassword(p); } return this->password; } public function getPersistent(Project p) { if (this->isReference()) { return this->getRef(p)->getPersistent(p); } return this->persistent; } /** * Gets a combined hash/array for DSN as used by PEAR. * @return array */ public function getPEARDSN(Project p) { if (this->isReference()) { return this->getRef(p)->getPEARDSN(p); } include_once 'DB.php'; dsninfo = DB::parseDSN(this->url); dsninfo['username'] = this->username; dsninfo['password'] = this->password; dsninfo['persistent'] = this->persistent; return dsninfo; } /** * Your datatype must implement this function, which ensures that there * are no circular references and that the reference is of the correct * type (DSN in this example). * * @return DSN */ public function getRef(Project p) { if ( !this->checked ) { stk = array(); array_push(stk, this); this->dieOnCircularReference(stk, p); } o = this->ref->getReferencedObject(p); if ( !(o instanceof DSN) ) { throw new BuildException(this->ref->getRefId()." doesn't denote a DSN"); } else { return o; } } } ### 6.7.2 Using the DataType The TypedefTask provides a way to "declare" your type so that you can use it in your build file. Here is how you would use this type in order to define a single DSN and use it for multiple tasks. (Of course you could specify the DSN connection parameters each time, but the premise behind needing a DSN datatype was to avoid specifying the connection parameters for each task.) <?xml version="1.0" ?> <project name="test" basedir="."> <typedef name="dsn" classname="myapp.types.DSN" /> <dsn id="maindsn" url="mysql://localhost/mydatabase" username="root" password="" persistent="false" /> <target name="main"> <my-special-db-task> <dsn refid="maindsn"/> </my-special-db-task> <my-other-db-task> <dsn refid="maindsn"/> </my-other-db-task> </target> </project> ### 6.7.3 Source Discussion #### Getters & Setters You must provide a setter method for every attribute you want to set from the XML build file. It is good practice to also provide a getter method, but in practice you can decide how your tasks will use your task. In the example above, we've provided a getter method for each attribute and we've also provided an additional method:DSN::getPEARDSN() which returns the DSN hash array used by PEAR::DB, PEAR::MDB, and Creole. Depending on the needs of the Tasks using this DataType, we may only wish to provide the getPEARDSN() method rather than a getter for each attribute. Also important to note is that the getter method needs to check to see whether the current DataType is a reference to a previously defined DataType -- the DataType::isReference() exists for this purpose. For this reason, the getter methods need to be called with the current project, because References are stored relative to a project. #### The getRef() Method The getRef() task needs to be implemented in your Type. This method is responsible for returning a referenced object; it needs to check to make sure the referenced object is of the correct type (i.e. you can't try to refer to a RegularExpresson from a DSN DataType) and that the reference is not circular. You can probably just copy this method from an existing Type and make the few changes that customize it to your Type. ## 6.8 Writing Mappers Writing your own filename mapper classes will allow you to control how names are transformed in tasks like CopyTask, MoveTask, XSLTTask, etc. In some cases you may want to extend existing mappers (e.g. creating a GlobMapper that also transforms to uppercase); in other cases, you may simply want to create a very specific name transformation that isn't easily accomplished with other mappers like GlobMapper or RegexpMapper. ### 6.8.1 Creating a Mapper Writing filename mappers is simplified by interface support in PHP5. Essentially, your custom filename mapper must implement phing.mappers.FileNameMapper. Here's an example of a filename mapper that creates DOS-style file names. For this example, the "to" and "from" attributes are not needed because all files will be transformed. To see the "to" and "from" attributes in action, look at phing.mappers.GlobMapper or phing.mappers.RegexpMapper. require_once "phing/mappers/FileNameMapper.php"; /** * A mapper that makes those ugly DOS filenames. */ class DOSMapper implements FileNameMapper { /** * The main() method actually performs the mapping. * * In this case we transform the sourceFilename into * a DOS-compatible name. E.g. * ExtendingPhing.html -> EXTENDI~.DOC * * @param string sourceFilename The name to be coverted. * @return array The matched filenames. */ public function main(sourceFilename) { info = pathinfo(sourceFilename); ext = info['extension']; // get basename w/o extension bname = preg_replace('/\.\w+\/', '', info['basename']); if (strlen(bname) > 8) { bname = substr(bname,0,7) . '~'; } if (strlen(ext) > 3) { ext = substr(bname,0,3); } if (!empty(ext)) { res = bname . '.' . ext; } else { res = bname; } return (array) strtoupper(res); } /** * The "from" attribute is not needed here, but method must exist. */ public function setFrom(from) {} /** * The "from" attribute is not needed here, but method must exist. */ public function setTo(to) {} } ### 6.8.2 Using the Mapper Assuming that this mapper is saved to myapp/mappers/DOSMapper.php (relative to a path on PHP's include_path, then you would refer to it like this in your build file: <mapper classname="myapp.mappers.DOSMapper"/> # Appendix A. Fact Sheet ## A.1 Built-In Properties Table A.1: Phing Built-In Properties PropertyContents application.startdirCurrent work directory env.*Environment variables, extracted from _SERVER. host.archSystem architecture, i.e. i586. Not available on Windows machines. host.domainDNS domain name, i.e. php.net. Not available on Windows machines. host.fstypeThe type of the files ystem. Possible values are UNIX, WINNT and WIN32 host.nameOperating System hostname as returned by posix_uname(). Not available on Windows machines. host.osOperating System description as set in PHP_OS variable (see PHP Manual). host.os.releaseOperating version release, i.e. 2.2.10. Not available on Windows machines. host.os.versionOperating system version, i.e. #4 Tue Jul 20 17:01:36 MEST 1999. Not available on Windows machines. line.separatorCharacter(s) that signal the end of a line, "\n" for Linux, "\r\n" for Windows system, "\r" for Macintosh. os.nameOperating System description as set in PHP_OS variable. phing.fileFull path to current buildfile. phing.dirPath that contains the current buildfile. phing.homePhing installation directory, not set in PEAR installations. phing.versionCurrent Phing version. phing.project.nameName of the currently processed project. php.classpathThe value of the PHP_CLASSPATH. Same as the include path returned by get_include_path(). php.versionVersion of the PHP interpreter. Same as PHP constant PHP_VERSION (see PHP Manual). project.basedirThe current project basedir. user.homeValue of the environment variable HOME. ## A.2 Command Line Arguments The following table lists the command line arguments currently available. Table A.2: Phing Command Line Arguments ParameterMeaning -h -helpDisplay the help screen -l -listList all available targets in buildfile (excluding targets that have their hidden attribute set to true) -v -versionPrint version information and exit -q -quietQuiet operation, no output at all -S -silentPrint nothing but task outputs and build failures -verboseVerbose, give some more output -debugOutput debug information -emacs -eProduce logging information without adornments -diagnosticsPrint diagnostics information -longtargetsShow target descriptions during build -logfile <file>Use given file for log -logger path.to.LoggerSpecify an alternate logger. Default is phing.listener.AnsiColorLogger. Other options include phing.listener.NoBannerLogger, phing.listener.DefaultLogger, phing.listener.XmlLogger, phing.listener.TargetLogger and phing.listener.HtmlColorLogger. -f -buildfile <file>Specify an alternate buildfile name. Default is build.xml -D<property>=<value>Set the property to the specified value to be used in the buildfile -keep-going -kExecute all targets that to not depend on failed target(s) -propertyfile <file>Load properties from the specified file -find <file>Search for a buildfile towards the root of the filesystem and use that -inputhandler <file>The class to use to handle user input ## A.3 Distribution File Layout PHING_HOME |-- bin |-- classes | -- phing | |-- filters | | -- util | |-- mappers | |-- parser | |-- tasks | | |-- ext | | |-- system | | | -- condition | | -- user | -- types |-- docs | -- phing_guide -- test |-- classes -- etc ## A.4 Program Exit Codes Phing is script-safe - means that you can execute Phing and Configure within a automated script context. To check back the success of a Phing call it returns an exit code that can be captured by your calling script. The following list gives you details on the used exit codes and their meaning. Table A.3: Program Exit Codes ExitcodeDescription -2Environment not properly defined -1Parameter or configuration error occurred 0Successful execution (build succeeded), no errors (there may be warnings) 1Unsuccessful execution (build failed), errors occurred ## A.5 The LGPL License  GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below. When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights. We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library. To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others. Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs. When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License. In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system. Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run. GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. &lt;one line to give the library's name and a brief idea of what it does.> Copyright (C) &lt;year> &lt;name of author> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library Frob' (a library for tweaking knobs) written by James Random Hacker. &lt;signature of Ty Coon>, 1 April 1990 Ty Coon, President of Vice That's all there is to it! ## A.6 The GFDL License  GNU Free Documentation License Version 1.3, 3 November 2008 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. The "publisher" means any person or entity that distributes copies of the Document to the public. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements". 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License. However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document. 11. RELICENSING "Massive Multiauthor Collaboration Site" (or "MMC Site") means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A "Massive Multiauthor Collaboration" (or "MMC") contained in the site means any set of copyrightable works thus published on the MMC site. "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization. "Incorporate" means to publish or republish a Document, in whole or in part, as part of another Document. An MMC is "eligible for relicensing" if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008. The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. # Appendix B. Core tasks This appendix contains a reference of all core tasks, i.e. all tasks that are needed to build a basic project. This reference lists the tasks alphabetically by the name of the classes that implement the tasks. So if you are searching for the reference to the <copy> tag, for example, you will want to look at the reference of CopyTask. ## B.1 AdhocTaskdefTask The AdhocTaskdefTask allows you to define a task within your build file. Note that you should use <![CDATA[ ... ]]> so that you don't have to quote entities within your <adhoc-task></adhoc-task> tags. Table B.1: Attributes NameTypeDescriptionDefaultRequired nameStringName of XML tag that will represent this task.n/aYes ### B.1.1 Examples <target name="main" description="==>test AdhocTask "> <adhoc-task name="foo"><![CDATA[ class FooTest extends Task { private bar; function setBar(bar) { this->bar = bar; } function main() { this->log("In FooTest: " . this->bar); } } ]]></adhoc-task> <foo bar="B.L.I.N.G"/> </target> ## B.2 AdhocTypedefTask The AdhocTypedefTask allows you to define a datatype within your build file. Note that you should use <![CDATA[ ... ]]> so that you don't have to quote entities within your <adhoc-type></adhoc-type> tags. Table B.2: Attributes NameTypeDescriptionDefaultRequired nameStringName of XML tag that will represent this datatype..n/aYes ### B.2.1 Example <target name="main" description="==>test AdhocType"> <adhoc-type name="dsn"><![CDATA[ class CreoleDSN extends DataType { private url; function setUrl(url) { this->url = url; } function getUrl() { return this->url; } } ]]></adhoc-type> <!-- creole-sql task doesn't exist; just an example --> <creole-sql file="test.sql"> <dsn url="mysql://root@localhost/test"/> </creole-sql> </target> ## B.3 AppendTask The Append Task appends text or contents of files to a specified file. In the example above, AppendTask is reading a filename from book/PhingGuide.book, processing the file contents with XSLT, and then appending the result to the file located at {process.outputfile}. This is a real example from the build file used to generate this book! Table B.3: Attributes NameTypeDescriptionDefaultRequired destFileFilePath of file to which text should be appended. If not specified the console will be used instead.n/aNo appendStringSpecifies whether or not the file specified by 'destfile' should be appended. Defaults to "yes".yesNo overwriteBooleanSpecifies whether or not the file specified by 'destfile' should be written to even if it is newer than all source files.yesNo fixlastlineBooleanSpecifies whether or not to check if each file concatenated is terminated by a new line. If this attribute is "yes" a new line will be appended to the stream if the file did not end in a new line. This attribute does not apply to embedded text.noNo eolStringSpecifies what the end of line character are for use by the fixlastline attribute. Valid values for this property are: • cr: a single CR • lf: a single LF • crlf: the pair CRLF • mac: a single CR • unix: a single LF • dos: the pair CRLF The default is platform dependent. For Unix platforms, the default is "lf". For DOS based systems (including Windows), the default is "crlf". For Mac OS, the default is "cr". n/aNo fileFilePath to file that should be appended to destFile.n/aNo textStringSome literal text to append to file.n/aNo ### B.3.1 Examples <append destFile="{process.outputfile}"> <filterchain> <xsltfilter style="{process.stylesheet}"> <param name="mode" expression="{process.xslt.mode}"/> </xsltfilter> </filterchain> <filelist dir="book/" listfile="book/PhingGuide.book"/> </append> ### B.3.2 Supported Nested Tags • filelist • fileset • filterchain • path • header, footer Used to prepend or postpend text into the concatenated stream. The text may be in-line or be in a file. Table B.4: Attributes NameTypeDescriptionDefaultRequired filteringBooleanWhether to filter the text provided by this sub element.yesNo fileStringA file to place at the head or tail of the concatenated text.n/aNo trimBooleanWhether to trim the value.noNo trimleadingBooleanWhether to trim leading white space on each line.noNo ## B.4 ApplyTask Applies a system command on each resource of the specified resource collection. When the os attribute is specified, then the command is only executed when run on one of the specified operating systems. The files of a number of Resource Collections – including but not restricted to FileSets, FileLists or DirSets – are passed as arguments to the system command. Table B.5: Attributes NameTypeDescriptionDefaultRequiredAlias executableStringThe command to execute without any command line arguments.n/aYes dirStringThe directory the command is to be executed in.n/aNo outputStringWhere to direct stdout.n/aNo errorStringWhere to direct stderr.n/aNo osStringOnly execute if the Appendix A, Fact Sheet property contains specified text.n/aNo escapeBooleanEscape shell metacharacters before execution. Setting this to true will enable the escape precaution.falseNo passthruBooleanWhether to use PHP's passthru() function instead of exec().falseNo spawnBooleanWhether to spawn unix programs to the background, redirecting stdout (output will not be logged by Phing).falseNo returnPropertyStringProperty name to set return value to from the execution.n/aNo outputPropertyStringProperty name to set output value to from the execution.n/aNo checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNofailonerror appendBooleanWhether output (and error) should be appended to or overwrite an existing file. If you set parallel to false, you will probably want to set this one to true.falseNo parallelBooleanRun the command only once, appending all files as arguments. If false, command will be executed once for every file.falseNo addsourcefileBooleanWhether source file name(s) should be added to the end of command-line automatically. If you need to place it somewhere different, use a nested <srcfile> element between your <arg> elements to mark the insertion point.trueNo relativeBooleanWhether the filenames should be passed on the command line as relative pathnames (relative to the base directory of the corresponding fileset/list for source files).falseNo forwardslashBooleanWhether the file names should be passed with forward slashes even if the operating system requires other file separator.falseNo maxparallelIntegerLimit the amount of parallelism by passing at most this many sourcefiles at once. Set it to <= 0 for unlimited.0No ### B.4.1 Examples <!-- Invokes somecommand arg1 SOURCEFILENAME arg2 for each file in /tmp --> <apply executable="somecommand" parallel="false"> <arg value="arg1"/> <srcfile/> <arg value="arg2"/> <fileset dir="/tmp"/> </apply> <!-- List all the .conf files of "/etc" to the "out.log" file. --> <apply executable="ls" output="/tmp/out.log" append="true" > <arg value="-alh" /> <fileset dir="/etc" > <include name="*.conf" /> </fileset> </apply>  ### B.4.2 Supported Nested Tags • arg Table B.6: Attributes NameTypeDescriptionDefaultRequired valueStringA single command-line argument; can contain space characters.n/aOne of these fileStringThe name of a file as a single command-line argument; will be replaced with the absolute filename of the file.n/a pathStringA string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Phing will convert it to the platform's local conventions.n/a lineStringA space-delimited list of command-line arguments.n/a • fileset • filelist • dirset • srcfile ## B.5 AttribTask Changes the attributes of a file or all files inside specified directories. Right now it has effect only under Windows. Each of the 4 possible permissions has its own attribute, matching the arguments for the attrib command. FileSets or FileLists can be specified using nested fileset and filelist elements. By default this task won't do anything unless it detects it is running on a Windows system. If you know for sure that you have a "attrib" executable on your PATH that is command line compatible with the Windows command, you can use the task's os attribute and set its value to your current os. Table B.7: Attributes NameTypeDescriptionDefaultRequired fileStringThe file or directory of which the permissions must be changed.n/aYes readonlyBooleanThe readonly permission.n/aat least one of the four. archiveBooleanThe archive permission.n/a systemBooleanThe system permission.n/a hiddenBooleanThe hidden permission.n/a verboseBooleanWhether to print a summary after execution or not. Defaults to false.falseNo osStringList of Operating Systems on which the command may be executed.n/aNo ### B.5.1 Example <attrib file="{dist}/run.bat" readonly="true" hidden="true"/> makes the "run.bat" file read-only and hidden. <attrib readonly="false"> <fileset dir="{meta.inf}" includes="**/*.xml"/> </attrib> makes all ".xml" files below {meta.inf} readable. ### B.5.2 Supported Nested Tags • filelist • fileset ## B.6 AvailableTask Available Task tests if a resource/file is set and sets a certain property to a certain value if it exists. Here, AvailableTask first checks for the existence of either file or directory named test.txt in /tmp. Then, it checks for the directory foo in /home and then for the file or directory bar in /home/foo. If /tmp/test.txt is found, the property test_txt_exists is set to "Yes", if /home/foo is found and a directory, properties.yetanother is set to "true" (default). If /home/foo/bar exists, AvailableTask will set foo.bar to "Well, yes". And last it checks if extension foo is loaded, so the property foo.ext.loaded is set to "true" (default). NB: the Available task can also be used as a condition, see conditions. Table B.8: Attributes NameTypeDescriptionDefaultRequired propertyStringName of the property that is to be set.n/aYes valueStringThe value the property is to be set to."true"No fileStringFile/directory to check existence.n/aYes (or resource or extension) resourceStringPath of the resource to look for.n/aYes (or file or extension) extensionStringName of the extension to look for.n/aYes (or file or resource) typeString (file|dir)Determines if AvailableTask should look for a file or a directory at the position set by file. If empty, it checks for either file or directory.n/aNo filepathStringThe path to use when looking up file.n/aNo followSymlinksBooleanWhether to dereference symbolic links when looking up file.falseNo ### B.6.1 Examples <available file="/tmp/test.txt" property="test_txt_exists" value="Yes"/> <available file="/home/foo" type="dir" property="properties.yetanother" /> <available file="/home/foo/bar" property="foo.bar" value="Well, yes" /> ## B.7 Basename Task to determine the basename of a specified file, optionally minus a specified suffix. When this task executes, it will set the specified property to the value of the last path element of the specified file. If file is a directory, the basename will be the last directory element. If file is a full-path, relative-path, or simple filename, the basename will be the simple file name, without any directory elements. Table B.9: Attributes NameTypeDescriptionDefaultRequired propertyStringName of the property that is to be set.n/aYes fileStringThe path to take the basename of.n/aYes suffixStringThe suffix to remove from the resulting basename (specified either with or without the ".").n/aNo ### B.7.1 Examples <basename property="cmdname" file="./foo.exe" suffix=".exe"/> ## B.8 ChmodTask Sets the mode of a file or directory. For more informations, see chmod in the PHP Manual. Table B.10: Attributes NameTypeDescriptionDefaultRequired fileStringThe name of the file or directory. You either have to specify this attribute, or use a fileset.n/aYes modeStringThe new mode (octal) for the file. Specified in octal, even if the first digit is not a '0'.n/aYes quietBooleanSet quiet mode, which suppresses warnings if chmod() failsfalseNo failonerrorBooleanThis flag means 'note errors to the output, but keep going'trueNo verboseBooleanGive more information in error message in case of a failuretrueNo ### B.8.1 Examples <chmod file="test.txt" mode="0755" /> <chmod file="/home/test" mode="0775" /> <chmod file="/home/test/mine.txt" mode="0500" verbose="true" /> ### B.8.2 Supported Nested Tags • fileset ## B.9 ChownTask Changes the owner of a file or directory. Table B.11: Attributes NameTypeDescriptionDefaultRequired fileStringThe name of the file or directory. You either have to specify this attribute, or use a fileset.n/aYes userStringThe new owner of the file. Can contain a username and a groupname, separated by a dot.n/aNo groupStringThe new group owner of the file.n/aNo quietBooleanSet quiet mode, which suppresses warnings if chmod() failsfalseNo failonerrorBooleanThis flag means 'note errors to the output, but keep going'trueNo verboseBooleanGive more information in error message in case of a failuretrueNo ### B.9.1 Examples <chown file="my-file.txt" user="foo" /> <chown file="my-file.txt" user="username.groupname" /> <chown file="/home/test/my-directory" user="bar" /> <chown file="/home/test/my-file.txt" user="foo" verbose="true" failonerror="false" /> ### B.9.2 Supported Nested Tags • fileset ## B.10 ConditionTask Sets a property if a certain condition holds true - this is a generalization of Section B.6, “AvailableTask ” and Section B.47, “UpToDateTask ”. If the condition holds true, the property value is set to true by default; otherwise, the property is not set. You can set the value to something other than the default by specifying the value attribute. Conditions are specified as nested elements, you must specify exactly one condition - see conditions for a complete list of nested elements. Table B.12: Attributes NameTypeDescriptionDefaultRequired propertyStringThe name of the property to set.n/aYes valueStringThe value to set the property to. Defaults to "true".trueNo elseStringThe value to set the property to if the condition evaluates to false. By default the property will remain unset.n/aNo ### B.10.1 Examples <condition property="isMacOrWindows"> <or> <os family="mac"/> <os family="windows"/> </or> </condition> ### B.10.2 Supported Nested Tags • or • and ## B.11 CopyTask Copies files or directories. Files are only copied if the source file is newer than the destination file, or when the destination file does not exist. It is possible to explicitly overwrite existing files. CopyTask does not allow self copying, i.e. copying a file to the same name for security reasons. Table B.13: Attributes NameTypeDescriptionDefaultRequired fileStringThe source file.Yes tofileString The destination the file is to be written to. tofile specifies a full filename. If you only want to specify a directory to copy to, use todir. Either this or the todir attribute is required. n/aYes (or todir) todirStringThe directory the file is to be copied to. The file will have the same name of the source file. If you want to specify a different name, use tofile. The directory must exist.n/aYes (or tofile) overwriteBooleanOverwrite existing files even if the destination files are newer.falseNo tstamp or preservelastmodifiedBooleanIf set to true, the new file will have the same mtime as the old one.falseNo preservemode or preservepermissionsBooleanIf set to true, the new file (and directory) will have the same permissions as the old one. The mode specified for directory creation will be ignored.trueNo includeemptydirsBooleanIf set to true, also empty directories are copied. trueNo modeIntegerMode (octal) to create directories with.From umaskNo haltonerrorBooleanIf set to true, halts the build when errors are encountered.trueNo ### Note No automatic expansion of symbolic links By default, CopyTask does not expand / dereference symbolic links, and will simply copy the link itself. To enable dereferencing, set expandsymboliclinks to true in the <fileset> tag. ### B.11.1 Examples On the one hand, CopyTask can be used to copy file by file: <copy file="somefile.txt" tofile="/tmp/anotherfile.bak" overwrite="true"/> Additionally, CopyTask supports Filesets, i.e. you can easily include/exclude one or more files. For more information, see Appendix D, Core Types -- pay particular attention to the defaultexcludes attribute. Appendix F, Core mappers and Appendix E, Core filters are also supported by CopyTask, so you can do almost everything that needs processing the content of the files or the filename. <copy todir="/tmp/backup" > <fileset dir="."> <include name="**/*.txt" /> <include name="**/*.doc" /> <include name="**/*.swx" /> </fileset> <filelist dir="." files="test.html"/> </copy> <copy todir="build" > <fileset defaultexcludes="false" expandsymboliclinks="true" dir="."> <include name="**/*.php" /> </fileset> </copy> ### B.11.2 Supported Nested Tags • fileset • filelist • filterchain • mapper ## B.12 DeleteTask Deletes a file or directory, or set of files defined by a fileset. See Appendix D, Core Types for information on Filesets. Table B.14: Attributes NameTypeDescriptionDefaultRequired fileStringThe file that is to be deleted. You either have to specify this attribute, dir, or use a fileset.n/aYes (or dir) dirStringThe directory that is to be deleted. You either have to specify this attribute, file, or use a fileset.n/aYes (or file) verboseBooleanUsed to force listing of all names of deleted files.n/aNo quietBoolean If the file does not exist, do not display a diagnostic message or modify the exit status to reflect an error. This means that if a file or directory cannot be deleted, then no error is reported. This setting emulates the -f option to the Unix rm command. Default is false meaning things are verbose n/aNo failonerrorBooleanIf this attribute is set to true, DeleteTask will verbose on errors but the build process will not be stopped.falseNo includeemptydirsBooleanDetermines if empty directories are also to be deleted.falseNo ### B.12.1 Examples <!-- Delete a specific file --> <delete file="/tmp/foo.bar" /> <!-- Delete a directory --> <delete dir="/tmp/darl" includeemptydirs="true" verbose="true" failonerror="true" /> <!-- Delete using a fileset --> <delete> <fileset dir="/tmp"> <include name="*.bar" /> </fileset> </delete> ### B.12.2 Supported Nested Tags • fileset ## B.13 Diagnostics Runs phing's -diagnostics code inside phing itself. This is good for debugging phing's configuration under an IDE. ### B.13.1 Example <target name="diagnostics" description="diagnostics"> <diagnostics/> </target> ## B.14 Dirname Task to determine the directory path of a specified file. When this task executes, it will set the specified property to the value of the specified file (or directory) up to, but not including, the last path element. If the specified file is a path that ends in a filename, the filename will be dropped. If the specified file is just a filename, the directory will be the current directory. Note: This is not the same as the UNIX dirname command, which is defined as "strip non-directory suffix from filename". <dirname> determines the full directory path of the specified file. Table B.15: Attributes NameTypeDescriptionDefaultRequired fileStringThe path to take the dirname of.n/ayes propertyStringThe name of the property to set.n/ayes ### B.14.1 Example <dirname property="foo.dirname" file="foo.txt"/> will set foo.dirname to the project's basedir. ## B.15 EchoTask Echoes a message to the current loggers and listeners which means standard out unless overridden. A level can be specified, which controls at what logging level the message is filtered at. The task can also echo to a file, in which case the option to append rather than overwrite the file is available, and the level option is ignored Additionally, the task can echo the contents of a nested fileset element. Table B.16: Attributes NameTypeDescriptionDefaultRequired msgStringThe string that is to be send to the output.n/aYes messageStringAlias for msg.n/aYes fileStringThe file to write the message to.n/aNo appendBooleanAppend to an existing file?falseNo levelStringControl the level at which this message is reported. One of error, warning, info, verbose, debug.infoNo ### B.15.1 Examples <echo msg="Phing rocks!" /> <echo message="Binarycloud, too." /> <echo>And don't forget Propel.</echo> <echo file="test.txt" append="false">This is a test message</echo> ### B.15.2 Supported Nested Tags • fileset ## B.16 EchoPropertiesTask Displays all the current properties in the project. The output can be sent to a file if desired. This task can be used as a somewhat contrived means of returning data from an <phing> invocation, but is really for debugging build files. Table B.17: Attributes NameTypeDescriptionDefaultRequired destfileStringIf specified, the value indicates the name of the file to send the output of the statement to. If not specified, then the output will go to the Phing log.n/ano srcfileStringIf specified, the value indicates the name of the property file to read from. If not specified, then the system properties will be taken.n/ano prefixStringa prefix which is used to filter the properties only those properties starting with this prefix will be echoed.n/ano regexStringa regular expression which is used to filter the properties only those properties whose names match it will be echoed.n/ano failonerrorBooleanBy default, the "failonerror" attribute is enabled. If an error occurs while writing the properties to a file, and this attribute is enabled, then a BuildException will be thrown, causing the build to fail. If disabled, then IO errors will be reported as a log statement, and the build will continue without failure from this task.n/ano formatStringOne of text or xml. Determines the output format. Defaults to text.n/ano ### B.16.1 Example <echoproperties /> Report the current properties to the log. <echoproperties destfile="my.properties"/> Report the current properties to the file "my.properties", and will fail the build if the file could not be created or written to. <echoproperties destfile="my.properties" failonerror="false"/> Report the current properties to the file "my.properties", and will log a message if the file could not be created or written to, but will still allow the build to continue. <echoproperties prefix="phing."/> List all properties beginning with "phing." <echoproperties regex="/.*phing.*/"/> Lists all properties that contain "phing" in their names. ## B.17 ExecTask Executes a shell command. You can use this to quickly add a new command to Phing. However, if you want to use this regularly, you should think about writing a Task for it. Table B.18: Attributes NameTypeDescriptionDefaultRequired commandStringThe command that is to be executed.n/aOne of the two executableStringThe command to execute without any command line arguments.n/a dirStringThe directory the command is to be executed in.n/aNo outputStringWhere to direct stdout.n/aNo errorStringWhere to direct stderr.Redirected to stdout, unless passthru is set to true.No osStringOnly execute if the Appendix A, Fact Sheet property contains specified text.n/aNo escapeBooleanBy default, we escape shell metacharacters before executing. Setting this to false will disable this precaution.falseNo passthruBooleanWhether to use PHP's passthru() function instead of exec().falseNo logoutputBooleanWhether to log returned output as MSG_INFO instead of MSG_VERBOSE.falseNo spawnBooleanWhether to spawn unix programs to the background, redirecting stdout.falseNo returnPropertyStringProperty name to set return value to from exec() call.n/aNo outputPropertyStringProperty name to set output value to from exec() call.n/aNo checkreturnBooleanWhether to check the return code of the program, throws a BuildException when returncode != 0.falseNo levelStringControl the level at which status messages are reported. One of error, warning, info, verbose, debug.verboseNo ### B.17.1 Examples <!-- List the contents of "/home". --> <exec command="ls -l" dir="/home" /> <!-- Start the make process in "/usr/src/php-4.0". --> <exec command="make" dir="/usr/src/php-4.0" /> <!-- List the contents of "/tmp" out to a file. --> <exec command="ls -l /tmp > foo.out" escape="false" /> ### B.17.2 Supported Nested Tags • arg Table B.19: Attributes NameTypeDescriptionDefaultRequired valueStringA single command-line argument; can contain space characters. To pass an empty argument, enclose two double quotes in single quotes ('""').n/aOne of these fileStringThe name of a file as a single command-line argument; will be replaced with the absolute filename of the file.n/a pathStringA string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Phing will convert it to the platform's local conventions.n/a lineStringA space-delimited list of command-line arguments.n/a escapeBooleanForce escape for this attribute.false ## B.18 FailTask Causes the current build script execution to fail and the script to exit with an (optional) error message. Table B.20: Attributes NameTypeDescriptionDefaultRequired messageStringThe message to display (reason for script abort)."No Message"No msgStringAlias for message"No Message"No ifStringName of property that must be set for script to exit.n/aNo unlessStringName of property that must not be set in order for script to exit.n/aNo statusIntegerExit using the specified status code; assuming the generated Exception is not caught, PHP will exit with this status.n/aNo ### B.18.1 Examples <!-- Exit w/ message --> <fail message="Failed for some reason!" /> <!-- Exit if {errorprop} is defined --> <fail if="errorprop" message="Detected error!" /> <!-- Exit unless {dontfail} prop is defined. --> <fail unless="dontfail" message="Detected error!" /> <!-- Using a condition to achieve the same effect: <fail message="Detected error!"> <condition> <not> <isset property="dontfail"/> </not> </condition> </fail> ### B.18.2 Parameters specified as nested elements. As an alternative to the if/unless attributes, conditional failure can be achieved using a single nested <condition> element, which should contain exactly one core or custom condition. ## B.19 ForeachTask The foreach task iterates over a list, a list of filesets, or both. If both, list and filesets, are specified, the list will be evaluated first. Nested filesets are evaluated in the order they appear in the task. Table B.21: Attributes NameTypeDescriptionDefaultRequired listStringThe list of values to process, with the delimiter character, indicated by the "delimiter" attribute, separating each value.n/aNo targetStringThe target to call for each token, passing the token as the parameter with the name indicated by the "param" attribute.n/aYes paramStringThe name of the parameter to pass the tokens in as to the target.n/aYes absparamStringThe name of the absolute pathparameter to pass the tokens in as to the target (used while processing nested filesets).n/aNo delimiterStringThe delimiter string that separates the values in the "list" parameter. The default is ",".,No ### B.19.1 Examples <!-- loop through languages, and call buildlang task with setted param --> <property name="languages" value="en,fr,de" /> <foreach list="{languages}" param="lang" target="buildlang" /> <!-- loop through files, and call subtask task with set param and absparam --> <foreach param="filename" absparam="absfilename" target="subtask"> <fileset dir="."> <include name="*.php"/> </fileset> </foreach> ### B.19.2 Supported Nested Tags • fileset • filelist • mapper ## B.20 IfTask Perform some tasks based on whether a given condition holds true or not. This task doesn't have any attributes, the condition to test is specified by a nested element - see the conditions for a complete list of nested elements. Just like the <condition> task, only a single condition can be specified - you combine them using <and> or <or> conditions. In addition to the condition, you can specify three different child elements, <elseif> , <then> and <else> . All three subelements are optional. Both <then> and <else> must not be used more than once inside the if task. Both are containers for Phing tasks. The <elseif> behaves exactly like an <if> except that it cannot contain the <else> element inside of it. You may specify as may of these as you like, and the order they are specified is the order they are evaluated in. If the condition on the <if> is false, then the first <elseif> who's conditional evaluates to true will be executed. The <else> will be executed only if the <if> and all <elseif> conditions are false. ### B.20.1 Examples <if> <equals arg1="{foo}" arg2="bar" /> <then> <echo message="The value of property foo is bar" /> </then> <else> <echo message="The value of property foo is not bar" /> </else> </if> <if> <equals arg1="{foo}" arg2="bar" /> <then> <echo message="The value of property foo is 'bar'" /> </then> <elseif> <equals arg1="{foo}" arg2="foo" /> <then> <echo message="The value of property foo is 'foo'" /> </then> </elseif> <else> <echo message="The value of property foo is not 'foo' or 'bar'" /> </else> </if> ## B.21 ImportTask Imports another build file into the current project. On execution it will read another Phing file into the same Project. Functionally it is nearly the same as copy and pasting the imported file onto the end of the importing file. The import task may only be used as a top-level task. This means that it may not be used in a target. Table B.22: Attributes NameTypeDescriptionDefaultRequired fileStringThe file to import.n/aYes optionalBooleanIf true, do not stop the build if the file does not exist.falseNo ### B.21.1 Target Overriding If a target in the main file is also present in at least one of the imported files, the one from the main file takes precedence. So if I import for example a docs/build.xml file named builddocs, that contains a "docs" target, I can redefine it in my main buildfile and that is the one that will be called. This makes it easy to keep the same target name, so that the overriding target is still called by any other targets--in either the main or imported buildfile(s)--for which it is a dependency, with a different implementation. The target from docs/build.xml is made available by the name "builddocs.docs". This enables the new implementation to call the old target, thus enhancing it with tasks called before or after it. ### B.21.2 Special Properties Imported files are treated as they are present in the main buildfile. This makes it easy to understand, but it makes it impossible for them to reference files and resources relative to their path. Because of this, for every imported file, Phing adds a property that contains the path to the imported buildfile. With this path, the imported buildfile can keep resources and be able to reference them relative to its position. So if I import for example a docs/build.xml file named builddocs, I can get its path as phing.file.builddocs, similarly to the phing.file property of the main buildfile. Additionally, the directory will be stored in phing.dir.builddocs. Note that "builddocs" is not the filename, but the name attribute present in the imported project tag. If import file does not have a name attribute, the phing.file.projectname and phing.dir.projectname properties will not be set. ### B.21.3 Resolving Files Against the Imported File Suppose your main build file called importing.xml imports a build file imported.xml , located anywhere on the file system, and imported.xml reads a set of properties from imported.properties : <!-- importing.xml --> <project name="importing" basedir="." default="..."> <import file="{path_to_imported}/imported.xml"/> </project> <!-- imported.xml --> <project name="imported" basedir="." default="..."> <property file="imported.properties"/> </project> This snippet however will resolve imported.properties against the basedir of importing.xml , because the basedir of imported.xml is ignored by Phing. The right way to use imported.properties is: <!-- imported.xml --> <project name="imported" basedir="." default="..."> <property file="{phing.file.imported}/imported.properties"/> </project> As explained above {phing.file.imported} stores the full path of the build script, that defines the project called imported, (in short it stores the path to imported.xml) and {phing.dir.imported} stores its directory. This technique also allows imported.xml to be used as a standalone file (without being imported in other project). ### B.21.4 Examples <import file="path/to/build.xml"/> <import file="path/to/build.xml" optional="true"/> Additionally, ImportTask supports Filesets, i.e. you can easily include/exclude one or more files. For more information, see Appendix D, Core Types. <import" > <fileset dir="."> <include name="path/to/build.xml" /> </fileset> <filelist dir="." files="path/to/build.xml"/> </import> ## B.22 IncludePathTask Modifies the PHP include_path configuration option for the duration of this phing run. The given path can be prepended (default) or appended to the current include path, or it can replace the include path. Table B.23: Attributes NameTypeDescriptionDefaultRequired classpathStringthe new include path[s]n/aYes classPathRefStringReference to a previously defined Path typen/aNo modeStringWhether to prepend, append or replace the include path with the given path.prependNo ### B.22.1 Examples <includepath classpath="new/path/here" /> <includepath classpath="path1:path2" /> <path id="project.class.path"> <pathelement dir="lib/"/> <pathelement dir="ext/"/> </paentry> <includepath classpathref="project.class.path" /> ## B.23 InputTask The InputTask can be used to interactively set property values based on input from the console (or other Reader). Table B.24: Attributes NameTypeDescriptionDefaultRequired propertyNameStringThe name of the property to set.n/aNo defaultValueStringThe default value to be set if no new value is provided.n/aYes messageStringPrompt text (same as CDATA).n/aYes promptCharStringThe prompt character to follow prompt text.n/aNo validArgsStringComma-separated list of valid choices the user must supply. If used, one of these options must be chosen.n/aNo ### B.23.1 Examples <!-- Getting string input --> <echo>HTML pages installing to: {documentRoot}</echo> <echo>PHP classes installing to: {servletDirectory}</echo> <input propertyname="documentRoot">Web application document root</input> <input propertyname="servletDirectory" defaultValue="/usr/servlets" promptChar="?">PHP classes install dir</input> <echo>HTML pages installed to {documentRoot}</echo> <echo>PHP classes installed to {servletDirectory}</echo> <!-- Having the user choose from a set of valid choices --> <echo>Choose a valid option:</echo> <input propertyname="optionsChoice" validargs="foo,bar,bob"> Which item would you like to use </input> ## B.24 LoadFileTask The LoadFileTask loads the contents of a (text) file into a single property. Table B.25: Attributes NameTypeDescriptionDefaultRequired propertyStringThe name of the property to set.n/aYes file (or srcFile)StringThe file to load.n/aYes failonerrorBooleanWhether to halt the build on failure.trueNo quietBooleanDo not display a diagnostic message (unless Phing has been invoked with the -verbose or -debug switches) or modify the exit status to reflect an error. Setting this to true implies setting failonerror to false.falseNo ### B.24.1 Examples <loadfile property="version" file="version.txt"/> ### B.24.2 Supported Nested Tags: • filterchain ## B.25 MkdirTask Creates a directory, including any necessary but non-existent parent directories. Does nothing if the directory already exists. Table B.26: Attributes NameTypeDescriptionDefaultRequired dirStringThe directory that is to be created.n/aYes modeIntegerThe mode to create the directory with.From umaskNo ### B.25.1 Examples <!-- Create a temp directory --> <mkdir dir="/tmp/foo" /> <!-- Using mkdir with a property --> <mkdir dir="{dirs.install}/tmp" />  ## B.26 MoveTask Moves a file or directory to a new file or directory. By default, the destination file is overwritten if it already exists. When overwrite is turned off, then files are only moved if the source file is newer than the destination file, or when the destination file does not exist. Source files and directories are only deleted if the file or directory has been copied to the destination successfully. ### B.26.1 Examples <!-- The following will move the file "somefile.txt" to "/tmp" and change its filename to "anotherfile.bak". It will overwrite an existing file. --> <move file="somefile.txt" tofile="/tmp/anotherfile.bak" overwrite="true"/> <!-- This will move the "/tmp" directory to "/home/default/tmp", preserving the directory name. So the final name is "/home/default/tmp/tmp". Empty directories are also copied --> <move file="/tmp" todir="/home/default/tmp" includeemptydirs="true" /> ### B.26.2 Attributes and Nested Elements For further documentation, see Section B.11, “CopyTask ”, since MoveTask only is a child of CopyTask and inherits all attributes. ## B.27 PathConvert Converts a path form for a particular platform, optionally storing the resultinto a given property. It can also be used when you need to convert FileList, FileSet, DirSet into a list, separated by a given character, such as a comma or space, or, conversely, e.g. to convert a list of files in a FileList into a path. Nested map elements can be specified to map Windows drive letters to Unix paths, and vice-versa. Table B.27: Attributes NameTypeDescriptionDefaultRequired targetosStringThe target architecture. This is a shorthand mechanism for specifying both pathsep and dirsep according to the specified target architecture.N/ANo dirsepString The character(s) to use as the directory separator in the generated paths.PhingFile::separatorNo pathsepStringThe character(s) to use as the path-element separator in the generated paths.PhingFile::pathSeparatorNo propertyStringThe name of the property in which to place the converted path.result will be logged if unsetNo refidStringWhat to convert, given as a reference to a path, fileset or dirset defined elsewhereif omitted, a nested path element must be supplied.No setonemptyBooleanShould the property be set, even if the result is the empty string?trueNo ## B.28 PhingTask This task calls another build file. You may specify the target that is to be called within the build file. Additionally, the <phing> Tag may contain <property> Tags (see Section B.32, “PropertyTask ”). Table B.28: Attributes NameTypeDescriptionDefaultRequired inheritAllBooleanIf true, pass all properties to the new phing project.trueNo inheritRefsBooleanIf true, pass all references to the new phing project.falseNo dirStringThe directory to use as a base directory for the new phing project. Default is the current project's basedir, unless inheritall has been set to false, in which case it doesn't have a default value. This will override the basedir setting of the called project.n/aNo phingFileStringThe build file to use. Defaults to "build.xml". This file is expected to be a filename relative to the dir attribute given.n/aYes targetStringThe target of the new Phing project to execute. Default is the new project's default target.n/aNo haltonfailureBooleanIf true, fail the build process when the called build failsfalseNo ### B.28.1 Examples <!-- Call target "xslttest" from buildfile "alternativebuildfile.xml" --> <phing phingfile="alternativebuild.xml" inheritRefs="true" target="xslttest" /> <!-- Do a more complex call --> <phing phingfile="somebuild.xml" target="sometarget"> <property name="foo" value="bar" /> <property name="anotherone" value="32" /> </phing> ### B.28.2 Supported Nested Tags • fileset ### B.28.3 Base directory of the new project The base directory of the new project is set dependent on the dir and the inheritAll attribute. This is important to keep in mind or else you might run into bugs in your build.xml's. The following table shows when which value is used: Table B.29: How attributes are used dirinheritAllnew project's basedir value providedtruevalue of dir attribute value providedfalsevalue of dir attribute omittedtruebasedir of calling task (the build file containing the <phing> call. omittedfalsebasedir attribute of the <project> element of the new project ## B.29 PhingCallTask The PhingCallTask calls a target within the same Phing project. A <phingcall> tag may contain <property> tags that define new properties. These properties are only set if properties of the same name have not been set outside the "phingcall" tag. When a target is invoked by phingcall, all of its dependent targets will also be called within the context of any new parameters. For example. if the target "doSomethingElse" depended on the target "init", then using phingcall to execute "doSomethingElse" will also execute "init". Note: the top level tasks of a project will always be executed! Table B.30: Attributes NameType/ValuesDescriptionDefaultRequired targetStringThe name of the target in the same project that is to be called.n/aYes ### Note Local scope. Every <phingcall> tag creates a new local scope. Thus, any properties or other variables set inside that scope will cease to exist (or revert to their previous value) once the <phingcall> tag completes. ### B.29.1 Examples <target name="foo"> <phingcall target="bar"> <property name="property1" value="aaaaa" /> <property name="foo" value="baz" /> </phingcall> </target> In the example above, the properties property1 and foo are defined and only accessible inside the called target. <target name="bar" depends="init"> <echo message="prop is {property1} {foo}" /> </target> ### B.29.2 Supported Nested Tags • property • param (alias for property) ## B.30 Phingversion Stores the Phing version (when used as task) or checks for a specific Phing version (when used as condition). Table B.31: Attributes NameTypeDescriptionRequired (Task)Required (Condition) atleastStringThe version that this at least. The format is major.minor.point.No One of these. exactlyStringThe version that this phing is exactly. The format is major.minor.point.No propertyStringThe name of the property to set.YesNo (ignored) ### B.30.1 Example <phingversion property="phingversion"/> Stores the current Phing version in the property phingversion. <phingversion property="phingversion" atleast="2.9"/> Stores the Phing version in the property phingversion if the current Phing version is 2.9.0 or higher. Otherwise the property remains unset. <phingversion property="phing-is-exact-292" exactly="2.9.2"/> Sets the property phing-is-exact-292 if Phing 2.9.2 is running. Neither 2.8.2 nor 2.9.1 would match. ## B.31 PhpEvalTask With the PhpEvalTask, you can set a property to the results of evaluating a PHP expression or the result returned by a function/method call. Table B.32: Attributes NameTypeDescriptionDefaultRequired functionStringThe name of the Property.n/aOne of these is required. expressionStringThe expression to evaluate.n/a classStringThe static class which contains function.n/aNo returnPropertyStringThe name of the property to set with result of expression or function call. Note: if this attribute is set, the expression must return a value.n/aNo levelStringControl the level at which php reports status messages. One of error, warning, info, verbose, debug.infoNo ### B.31.1 Examples <php function="crypt" returnProperty="enc_passwd"> <param value="{auth.root_passwd}"/> </php> <php expression="3 + 4" returnProperty="sum"/> <php expression="echo 'test';"> ### B.31.2 Supported Nested Tags • param ## B.32 PropertyTask With PropertyTask, you can define user properties in your build file. Table B.33: Attributes NameTypeDescriptionDefaultRequired nameStringThe name of the Property.n/aYes (unless using file or environment) valueStringThe value of the Property.n/aYes (unless using file or environment) environmentStringLoads properties from the environment with the specified value as prefix. Thus if you specify environment="myenv" you will be able to access OS-specific environment variables via property names "myenv.PATH" or "myenv.TERM".n/aNo fileStringPath to properties file.n/aNo overrideBooleanWhether to force override of existing value.falseNo prefixStringUsed when properites are loaded from file. Prefix is applied to properties loaded from specified file. A "." is appended to the prefix if not specified.n/aNo refidStringA reference to a previously defined propeprtyn/aNo fallbackStringIf a reference cannot be found within the current project scope this attribute specifies a fallback project scope.n/aNo logoutputBooleanWhether to log returned output as MSG_INFO instead of MSG_VERBOSE.trueNo ### Note Important note about scope: when the <property> tag is called inside a <phingcall> tag, any properties are set in a new local scope. Thus, any properties or other variables set inside that scope will cease to exist (or revert to their previous value) once the parent <phingcall> tag completes. ### B.32.1 Examples <property name="strings.test" value="Harr harr, more power!" /> <echo message="{strings.test}" /> <property name="foo.bar" value="Yet another property..." /> <echo message="{foo.bar}" /> <property file="build.properties" /> <property environment="env" /> <property name="newproperty" value="Hello"> <filterchain> <replaceregexp> <regexp pattern="Hello" replace="World" ignoreCase="true"/> </replaceregexp> </filterchain> </property> ### B.32.2 Supported Nested Tags: • filterchain ## B.33 PropertyPromptTask PropertyPromptTask is a simple task to read in user input into a property. If you need something more advanced, see the Section B.23, “InputTask ”. Table B.34: Attributes NameTypeDescriptionDefaultRequired propertyNameStringThe name of the Property to set.n/aYes promptTextStringThe text to use for the prompt.n/aYes promptCharacterStringThe character to use after the prompt.?No defaultValueStringA default value to use (if user just hits enter).n/aNo useExistingValueStringWhether existing property should be used if available. (This will result in user only being prompted if the propertyName property is not already set.)falseNo ### B.33.1 Examples <propertyprompt propertyName="someprop" defaultValue="/var/www" promptText="Enter your web root" /> <echo>{someprop}</echo> ## B.34 Record A recorder is a listener to the current build process that records the output to a file. Several recorders can exist at the same time. Each recorder is associated with a file. The filename is used as a unique identifier for the recorders. The first call to the recorder task with an unused filename will create a recorder (using the parameters provided) and add it to the listeners of the build. All subsequent calls to the recorder task using this filename will modify that recorders state (recording or not) or other properties (like logging level). Some technical issues: the file's output stream is flushed for "finished" events (buildFinished, targetFinished and taskFinished), and is closed on a buildFinished event. Table B.35: Attributes NameTypeDescriptionDefaultRequired nameStringThe name of the file this logger is associated with.n/ayes actionStringThis tells the logger what to do: should it start recording or stop? The first time that the recorder task is called for this logfile, and if this attribute is not provided, then the default for this attribute is "start". If this attribute is not provided on subsequent calls, then the state remains as previous. [Values = {start|stop}, Default = no state change]n/ano appendBooleanShould the recorder append to a file, or create a new one? This is only applicable the first time this task is called for this file. [Values = {yes|no}, Default=no]nono emacsmodeBooleanRemoves [task] banners like Phings's -emacs command line switch if set to true.falseno loglevelStringAt what logging level should this recorder instance record to? This is not a once only parameter (like append is) -- you can increase or decrease the logging level as the build process continues. [Values= {error|warn|info|verbose|debug}, Default = no change]falseno ### B.34.1 Example The following build.xml snippet is an example of how to use the recorder to record just the <echo> task: ... <record name="log.txt" action="start"/> <echo ... <record name="log.txt" action="stop"/> ... The following two calls to <record> set up two recorders: one to file "records-simple.log" at logging level info (the default) and one to file "ISO.log" using logging level of verbose. ... <record name="records-simple.log"/> <record name="ISO.log" loglevel="verbose"/> ... ## B.35 ReflexiveTask The ReflexiveTask performs operations on files. It is essentially a convenient way to transform (using filter chains) files without copying them. Table B.36: Attributes NameTypeDescriptionDefaultRequired fileStringA single file to be processed.n/aYes (unless <fileset> provided) ### B.35.1 Examples <reflexive> <fileset dir="."> <include pattern="*.html"> </fileset> <filterchain> <replaceregexp> <regexp pattern="\r(\n)" replace="\1"/> </replaceregexp> </filterchain> </reflexive> ### B.35.2 Supported Nested Tags: • fileset • filterchain ## B.36 ResolvePathTask The ResolvePathTask turns a relative path into an absolute path, with respect to specified directory or the project basedir (if no dir attribute specified). This task is useful for turning a user-defined relative path into an absolute path in cases where buildfiles will be called in different directories. Without this task, buildfiles lower in the directory tree would mis-interpret the user-defined relative paths. Table B.37: Attributes NameTypeDescriptionDefaultRequired fileStringThe file or directory path to resolve.n/aYes dirFileThe base directory to use when resolving "file".project.basedirNo propertyNameStringThe name of the property to set with resolved (absolute) path.n/aYes levelStringControl the level at which status messages are reported. One of error, warning, info, verbose, debug.verboseNo ### B.36.1 Examples <property name="relative_path" value="./dirname"/> <resolvepath propertyName="absolute_path" file="{relative_path}"/> <echo>Resolved [absolute] path: {absolute_path}</echo> ## B.37 Retry Retry is a container which executes a single nested task until either: there is no failure; or: its retrycount has been exceeded. If this happens a BuildException is thrown.. Table B.38: Attributes NameTypeDescriptionDefaultRequired retrycountIntegernumber of times to attempt to execute the nested task 1Yes retrydelayIntegernumber of seconds to wait between retry attempts task. 0No, defaults to no delay Any valid Phing task may be embedded within the retry task. ### B.37.1 Example <retry retrycount="3"> <httpget url="http://www.unreliable-server.com/unreliable.tar.gz" dir="/home/retry"/> </retry> This example shows how to use <retry> to wrap a task which must interact with an unreliable network resource. ## B.38 SleepTask A task for sleeping a short period of time, useful when a build or deployment process requires an interval between tasks. Table B.39: Attributes NameTypeDescriptionDefaultRequired hoursIntegerhours to to add to the sleep time0no minutesIntegerminutes to add to the sleep time0no secondsIntegerseconds to add to the sleep time0no millisecondsIntegermilliseconds to add to the sleep time0no failonerrorBooleanflag controlling whether to break the build on an error.trueNo ### B.38.1 Example <sleep seconds="2"/> ## B.39 SwitchTask Task definition for the phing task to switch on a particular value. Table B.40: Attributes NameTypeDescriptionDefaultRequired valueStringThe value to switch on.n/aYes caseinsensitiveBooleanShould we do case insensitive comparisons?falseNo ### B.39.1 Supported Nested Tags At least one <case> or <default> is required. case An individual case to consider, if the value that is being switched on matches to value attribute of the case, then the nested tasks will be executed. Table B.41: Attributes NameTypeDescriptionDefaultRequired valueStringThe value to match against the tasks value attribute.n/aYes default The default case for when no match is found. Must not appear more than once per task. ### B.39.2 Examples <switch value="{foo}"> <case value="bar"> <echo message="The value of property foo is bar" /> </case> <case value="baz"> <echo message="The value of property foo is baz" /> </case> <default> <echo message="The value of property foo is not sensible" /> </default> </switch> ## B.40 TaskdefTask With the TaskdefTask you can import a user task into your buildfile. Table B.42: Attributes NameTypeDescriptionDefaultRequired classnameStringThe path to the class that defines the TaskClass.n/aYes, unless the file attribute has been specified. nameStringThe name the task is available as after importing. If you specify "validate", for example, you can access the task imported here with <validate>.n/aYes, unless the file attribute has been specified. fileStringName of the file to load definitions from.n/aNo classpathStringThe classpath to use when including classes. This is added to PHP's include_path.n/aNo classpathrefStringReference to classpath to use when including classes. This is added to PHP's include_path.n/aNo ### B.40.1 Examples <!-- Includes the Task named "ValidateHTMLTask" and makes it available by <validatehtml> --> <taskdef classname="user.tasks.ValidateHTMLTask" name="validatehtml" /> <!-- Includes the Task "RebootTask" from "user/sometasks" somewhere inside the PHP_CLASSPATH --> <taskdef classname="user.sometasks.RebootTask" name="reboot" /> <!-- Includes all tasks from the property file. Each line in the property file defines a task in the format: name=path.to.Task --> <taskdef file="/path/to/mytasks.properties" /> NB: Taskdef now supports the PEAR-style naming convention to define and load tasks: <taskdef name="sampletask" classname="Dir_Subdir_SampleTask"/> will load class Dir_Subdir_SampleTask from file Dir/Subdir/SampleTask.php. ### B.40.2 Supported Nested Tags • classpath ## B.41 Tempfile Task This task sets a property to the name of a temporary file. Unlike PhingFile::createTempFile(), this task does not actually create the temporary file, but it does guarantee that the file did not exist when the task was executed. Table B.43: Attributes NameTypeDescriptionDefaultRequired propertyStringSets the property you wish to assign the temporary file to.n/ayes destdirStringSets the destination directory. If not set, the basedir directory is used instead.basedirno prefixStringSets the optional prefix string for the temp file.n/ano suffixStringSets the optional suffix string for the temp file.n/ano deleteonexitBooleanWhether the temp file will be marked for deletion on normal exit (even though the file may never be created).falseno createfileBooleanWhether the temp file should be created by this task.falseno ### B.41.1 Example <tempfile property="temp.file"/> create a temporary file <tempfile property="temp.file" suffix=".xml"/> create a temporary file with the .xml suffix <tempfile property="temp.file" destDir="build"/> create a temporary file in the build subdirectory ## B.42 TouchTask The TouchTask works like the Unix touch command: It sets the modtime of a file to a specific time. Default is the current time. Table B.44: Attributes NameTypeDescriptionDefaultRequired fileStringThe file which time is to be changed.n/aYes, or nested <fileset> tag datetimeDateTimeThe date and time the mtime of the file is to be set to. The format is "MM/DD/YYYY HH:MM AM or PM"nowNo millisIntegerThe number of milliseconds since Midnight Jan 1 1970 (Unix epoche).nowNo mkdirsBooleanWhether to create nonexistent parent directories when touching new files.falseNo verboseBooleanWhether to log the creation of new files.trueNo ### B.42.1 Examples <touch file="README.txt" millis="102134111" /> <touch file="COPYING.lib" datetime="10/10/1999 09:31 AM" /> ### B.42.2 Supported Nested Tags • fileset ## B.43 TruncateTask Set the length of one file, as the intermittently available truncate Unix utility/function. Table B.45: Attributes NameTypeDescriptionDefaultRequired fileStringThe name of the file.n/aYes lengthIntegerSpecifies the new file length (in bytes) to set.n/aNo adjustIntegerSpecifies the number of bytes (and positive/negative direction) by which to adjust file lengths.n/aNo createBooleanWhether to create nonexistent files.trueNo mkdirsBooleanWhether to create nonexistent parent directories when creating new files.falseNo ### B.43.1 Examples <truncate file="foo" /> ## B.44 TryCatchTask This task is a wrapper task that lets you run tasks(s) when another set of tasks fails, mirroring PHP's try/catch functionality (with the addition of finally block) The tasks inside of the try block will always be run. If one of them throws a BuildException, the following things can happen: • If there is no catch block, the exception will be passed to Phing. • If the property attribute has been set a property of that name will contain the message of the exception. • If there is a catch block, the nested tasks will be run. If a finally block is present, the nested tasks will be run regardless of whether the tasks in the try block have thrown an exception or not. This task was inspired by http://ant-contrib.sourceforge.net/tasks/tasks/trycatch.html. Table B.46: Attributes NameTypeDescriptionDefaultRequired propertyStringName of a property that will receive the message of the exception that has been caught (if any)n/aNo ### B.44.1 Examples <trycatch property="foo"> <try> <fail>Tada!</fail> </try> <catch> <echo>In catch.</echo> </catch> <finally> <echo>In finally.</echo> </finally> </trycatch> <echo>As property: {foo}</echo> ## B.45 TstampTask Sets the DSTAMP, TSTAMP, and TODAY properties in the current project. By default, the DSTAMP property is in the format "%Y%m%d", TSTAMP is in the format "%H%M", and TODAY is in the format "%B %d %Y". Use the nested <format> element to specify a different format. These properties can be used in the build-file, for instance, to create time-stamped filenames, or used to replace placeholder tags inside documents to indicate, for example, the release date. The best place for this task is probably in an initialization target. Table B.47: Attributes NameTypeDescriptionDefaultRequired prefixStringPrefix used for all properties set.n/aNo ### B.45.1 Examples <tstamp/> sets the standard DSTAMP, TSTAMP, and TODAY properties according to the default formats. <tstamp> <format property="DATE" pattern="%c" locale="nl_NL"/> </tstamp> sets the standard properties as well as the property DATE with the date/time pattern "%c" using the Dutch locale. <tstamp prefix="start"/> sets three properties with the standard formats, prefixed with "start.": start.DSTAMP, start.TSTAMP, and start.TODAY. ### B.45.2 Supported Nested Tags • format The Tstamp task supports a <format> nested element that allows a property to be set to the current date and time in a given format. The date/time patterns are as defined in the PHP strftime() function. Table B.48: Attributes NameTypeDescriptionDefaultRequired propertyStringThe property to receive the date/time string in the given pattern.n/aYes patternStringThe date/time pattern to be used. The values are as defined by the PHP strftime() function.n/aYes localeStringThe locale used to create date/time string. For more information see the PHP setlocale() function.n/aNo timezoneStringThe timezone to use for displaying time.n/aNo ## B.46 TypedefTask With the TypedefTask you can import a user type into your buildfile. Table B.49: Attributes NameTypeDescriptionDefaultRequired classnameStringThe path to the class that defines the type class.n/aYes nameStringThe name the type is available as after importing. If you specify "cproject", for example, you can access the type imported here with <cproject>.n/aYes classpathStringThe classpath to use when including classes. This is added to PHP's include_path.n/aNo classpathrefStringReference to classpath to use when including classes. This is added to PHP's include_path.n/aNo ### B.46.1 Examples <!-- Includes the Type named "CustomProject" and makes it available by <cproject> --> <typedef classname="user.types.CustomProject" name="cproject" /> ### B.46.2 Supported Nested Tags • classpath ## B.47 UpToDateTask UpToDateTask tests if a file is newer than another file or files and sets a property if it is. This is a common way to avoid, possibly time consuming, creation of a target if none of the files/resources it depends on have changed. Table B.50: Attributes NameTypeDescriptionDefaultRequired propertyStringName of the property that is to be setn/aYes valueStringThe value the property is to be set totrueNo srcfileStringThe file to check against target file(s)n/aYes (or nested fileset) targetfileStringThe file for which we want to determine the statusn/aYes (or nested mapper) ### B.47.1 Examples <uptodate property="propelBuild.notRequired" targetfile="{deploy}/propelClasses.tgz"> <fileset dir="{src}/propel"> <include="**/*.php"/> </fileset> </uptodate> The above example sets the property propelBuild.notRequired to true if the {deploy}/propelClasses.tgz file is more up-to-date than any of the PHP class files in the {src}/propel directory. <target name="CompileTarget"> <uptodate property="target.uptodate" targetfile="main"> <fileset refid="sources"/> </uptodate> <if> <not><isset property="target.uptodate"/></not> <then> <!-- Some commands to update the target ... --> </then> </if> </target> The above example shows a common use when doing a "compile" type target where a single target depends on other source files. In this case the commands to update the target (whatever they are) are only run if any of the source files are more up to date than the target. ### B.47.2 Supported Nested Tags • filelist • fileset • mapper ## B.48 WaitForTask Wait for a condition to become true or a timeout, whichever comes first. Table B.51: Attributes NameTypeDescriptionDefaultRequired MaxWaitIntegerSet the maximum length of time to wait in units3minYes MaxWaitUnitStringSet the max wait time unit. Must be one of "week","day", "hour", "minute", "second", "millisecond"millisecondNo CheckEveryIntegerSet the time between each check500msYes CheckEveryUnitStringSet the check every time unit. Must be one of "week","day", "hour", "minute", "second", "millisecond"millisecondsNo TimeoutPropertyStringName of the property to set after a timeout. nullNo ### B.48.1 Examples Wait for a maximum of ten seconds for the file "ready" to appear. <waitfor maxwaitunit="second" maxwait="10"> <available file="ready"/> </waitfor>  ### B.48.2 Supported Nested Tags All conditionals including and, or, not etc. ## B.49 XsltTask With XsltTask, you can run a XSLT transformation on an XML file. Actually, XsltTask extends CopyTask, so you can use all the elements allowed there. XsltTask is implemented by means of the XsltFlter and hence relies on PHP5 XSLT support via (libxslt) which must be available in php5. The XsltTask is equivalent to running command line xsltproc since that is a frontend for libxslt. Table B.52: Attributes NameTypeDescriptionDefaultRequired styleStringThe path where the Xslt file is locatedn/aYes resolvedocumentexternalsBooleanWhether to resolve entities in the XML document. (see this link for details)falseNo resolvestylesheetexternalsBooleanWhether to resolve entities in the stylesheet.falseNo Note: You can also use all the attributes available for Section B.11, “CopyTask ”. ### B.49.1 Examples <!-- Transform docbook with an imaginary XSLT file --> <xslt todir="/srv/docs/phing" style="dbk2html.xslt" > <fileset dir="."> <include name="**/*.xml" /> </fileset> </xslt> ### B.49.2 Supported Nested Tags • mapper • filterchain • param Note: You can use all the elements also available for Section B.11, “CopyTask ”. Additionally, you can use <param> tags with a name and a expression (or value alias) attribute. These parameters are then available from within the xsl style sheet. # Appendix C. Optional tasks This appendix contains a reference of all optional tasks, i.e. tasks that are not directly needed for building projects, but can assist in various aspects of development and deployment. This reference lists the tasks alphabetically by the name of the classes that implement the tasks. So if you are searching for the reference to the <phplint> tag, for example, you will want to look at the reference of PhpLintTask. ## C.1 ApiGenTask This task runs ApiGen, a tool for creating professional API documentation from PHP source code, similar to discontinued phpDocumentor/phpDoc. Table C.1: Attributes NameTypeDescriptionDefaultRequired executableStringApiGen executable name.apigenNo actionStringApiGen action to be executed.generateNo configStringConfig file name.n/aSource and destination are required - either set explicitly or using a config file. Attribute values set explicitly have precedence over values from a config file. sourceStringList of source files or directories.n/a destinationStringDestination directory.n/a excludeStringList of masks (case sensitive) to exclude files or directories from processing.n/aNo skipdocpathStringList of masks (case sensitive) to exclude elements from documentation generating.n/aNo charsetStringCharacter set of source files.UTF-8No mainStringMain project name prefix.n/aNo titleStringTitle of generated documentation.n/aNo baseurlStringDocumentation base URL.n/aNo googlecseidStringGoogle Custom Search ID.n/aNo googlecselabelStringGoogle Custom Search label.n/aNo googleanalyticsStringGoogle Analytics tracking code.n/aNo templateconfigStringTemplate config file name.n/aIf not set the default template is used. templatethemeStringTemplate theme file name.n/aIf not set the default template is used. accesslevelsStringElement access levels. Documentation only for methods and properties with the given access level will be generated.public, protectedNo internalBooleanWhether to generate documentation for elements marked as internal and internal documentation parts or not.NoNo phpBooleanWhether to generate documentation for PHP internal classes or not.YesNo treeBooleanWhether to generate tree view of classes, interfaces, traits and exceptions or not.YesNo deprecatedBooleanWhether to generate documentation for deprecated elements or not.NoNo todoBooleanWhether to generate documentation of tasks or not.NoNo sourcecodeBooleanWhether to generate highlighted source code files or not.YesNo downloadBooleanWhether to generate a link to download documentation as a ZIP archive or not.NoNo debugBooleanWhether to enable the debug mode or not.NoNo ### C.1.1 Example <apigen source="classes" destination="api" exclude="*/tests/*" title="My Project API Documentation" deprecated="true" todo="true"/> ## C.2 AutoloaderTask The AutoloaderTask includes autoload file to bootstrap all necessary components in Phing execution context. It could be useful if build tools (e.g. phpunit, phploc etc.) are installed as Composer dependencies. Table C.2: Attributes NameTypeDescriptionDefaultRequired autoloaderpathStringPath to autoloader filevendor/autoload.phpYes ### C.2.1 Example <autoloader autoloaderpath="foo/autoload.php"/> ## C.3 ComposerTask The ComposerTask runs the Composer tool (http://getcomposer.org) directly from Phing. Table C.3: Attributes NameTypeDescriptionDefaultRequired phpStringPath to the PHP interpreterDefaults to the {php.interpreter} property which is the interpreter used to execute phing itself.No composerStringPath to Composer.composer.pharNo commandStringThe Composer command to execute.n/aNo ### C.3.1 Supported Nested Tags • arg Table C.4: Attributes NameTypeDescriptionDefaultRequired valueStringA single command-line argument; can contain space characters.n/aOne of these fileStringThe name of a file as a single command-line argument; will be replaced with the absolute filename of the file.n/a pathStringA string that will be treated as a path-like string as a single command-line argument; you can use ; or : as path separators and Phing will convert it to the platform's local conventions.n/a lineStringA space-delimited list of command-line arguments.n/a ## C.4 CoverageMergerTask The CoverageMergerTask merges code coverage information from external sources with an existing code coverage database. The format of the code coverage files is expected to be identical to: file_put_contents( '/www/live/testcases/coverage.data', serialize(xdebug_get_code_coverage) ); ### C.4.1 Example <coverage-merger> <fileset dir="/www/live/testcases"> <include name="**/*.data"/> </fileset> </coverage-merger> ### C.4.2 Supported Nested Tags • fileset ## C.5 CoverageReportTask The CoverageReportTask formats a coverage database into a framed HTML report using XSLT. The report can optionally make use of the Generic Syntax Highlighting library, GeSHi (See GeSHi Homepage) library to mark up source code. The path to the library (if not in the default path) can be specified as an attribute. Table C.5: Attributes NameTypeDescriptionDefaultRequired outfileStringThe location for the intermediate XML file.coverage.dbYes classpathStringAdditional classpath to locate source referenced in the report.n/aNo geshipathStringPath to GeSHi highlighting library.n/aNo/Yes* If syntax highlighting is to be enabled geshilanguagespathStringLanguage to use with GeSHi.n/aNo ### C.5.1 Example <coverage-report outfile="reports/coverage.xml"> <report todir="reports/coverage" styledir="/home/phing/etc"/> </coverage-report> ### C.5.2 Supported Nested Tags • report Table C.6: Attributes NameTypeDescriptionDefaultRequired styledirStringThe directory where the stylesheets are located.The etc directory in the Phing installation.No todirStringThe directory where the files resulting from the transformation should be written to. Yes titleStringTitle of the project (used in the generated document(s)). No usesorttableBooleanWhether to use the sorttable JavaScript library (see http://www.kryogenix.org/code/browser/sorttable/).falseNo ## C.6 CoverageSetupTask The CoverageSetupTask prepares a database which can be used to gather code coverage information for unit tests. Table C.7: Attributes NameTypeDescriptionDefaultRequired databaseStringThe location for the coverage database.coverage.dbYes ### C.6.1 Example <coverage-setup database="./reports/coverage.db"> <fileset dir="classes"> <include name="**/*.php"/> </fileset> </coverage-setup> <phpunit codecoverage="true"> <batchtest> <fileset dir="src"> <include name="*Test.php"/> </fileset> </batchtest> </phpunit> ### C.6.2 Supported Nested Tags • classpath • fileset • filelist ## C.7 CoverageThresholdTask This task validates the code coverage database and will stop the build cycle if any class or method or entire project's coverage is lower than the specified threshold. Table C.8: Attributes NameTypeDescriptionDefaultRequired databaseStringThe location of the coverage database. (This is optional if CoverageSetupTask has run before.)n/aNo perProjectIntegerThe minimum code coverage for the entire project.25No perClassIntegerThe minimum code coverage for any class.25No perMethodIntegerThe minimum code coverage for any method.25No verboseBooleanWhether to enable detailed logging or not.falseNo ### C.7.1 Example <coverage-threshold database="./reports/coverage.db"/> ### C.7.2 Supported Nested Tags • classpath • excludes Validates an optional code coverage database against the default thresholds. <coverage-threshold perProject="50" perClass="60" perMethod="70"/> Validates the code coverage database (from CoverageSetupTask) against the specified thresholds. <coverage-threshold perProject="50" perClass="60" perMethod="70"/> <excludes> <file>**/*Processor.php</file> <class>Model_Filter_Windows</class> <method>Model_System::execute()</method> </excludes> Validates the code coverage database (from CoverageSetupTask) against the specified thresholds and excludes the given file, class and method from threshold validation. The filename is relative to the project basedir. A Method can be named either "Model_System::execute()" or "Model_System::execute". The method name is considered only for the given class "Model_System". ## C.8 DbDeployTask The DbDeployTask creates .sql files for making revisions to a database, based on dbdeploy conventions centering around a changelog table in the database. See rules for using dbdeploy for more information. You will need a changelog table like so: Table C.9: Attributes NameTypeDescriptionDefaultRequired urlStringPDO connection urln/aYes useridStringDB userid to use for accessing the changelog table.noneAs required by db passwordStringDB password to use for accessing the changelog table.noneAs required by db dirStringDirectory containing dbdeploy delta scripts.noneYes outputfileStringFilename in which deployment SQL will be generated.dbdeploy_deploy.sqlNo undooutputfileStringFilename in which undo SQL will be generated.dbdeploy_undo.sqlNo deltasetStringdeltaset to check within db.MainNo lastchangetoapplyIntegerHighest-numbered delta script to apply to db.999No appliedByStringValue of the 'applied_by' column for each entry in the changelog table.dbdeployNo checkallBooleanFalse means dbdeploy will only apply patches that have a higher number than the last patchnumber that was applied True means dbdeploy will apply all changes that aren't applied already (in ascending order).falseNo ### C.8.1 Example CREATE TABLE changelog ( change_number BIGINT NOT NULL, delta_set VARCHAR(10) NOT NULL, start_dt TIMESTAMP NOT NULL, complete_dt TIMESTAMP NULL, applied_by VARCHAR(100) NOT NULL, description VARCHAR(500) NOT NULL ) <dbdeploy url="sqlite:{project.basedir}/data/db.sqlite" userid="dbdeploy" password="dbdeploy" dir="{project.basedir}/data/dbdeploy/deltas" /> The above example uses a sqlite database and delta scripts located in dbdeploy/deltas in the project base dir. ## C.9 ExportPropertiesTask Exports all defined properties to a specified file. Table C.10: Attributes NameTypeDescriptionDefaultRequired targetfileStringTarget file for saved properties.n/aYes disallowedPropertyPrefixesStringExclude properties starting with these prefixes (separated by ,'host.', 'phing.', 'os.', 'php.', 'line.', 'env.', 'user.'No ### C.9.1 Example <exportproperties targetfile="output.props" /> ## C.10 FileHashTask Calculates either MD5 or SHA1 hash value of a file and stores the value as a hex string in a property. Other popular algorithms like "crc32" or "sha512" may be used with help of the algorithm attribute. Table C.11: Attributes NameTypeDescriptionDefaultRequired fileStringFilenamen/aYes hashtypeIntegerSpecifies what hash algorithm to use. 0=MD5, 1=SHA10No algorithmStringSpecifies what hash algorithm to use. Supported algorithms. n/aNo propertynameStringName of property where the hash value is stored.filehashvalueNo ### C.10.1 Example <filehash file="{builddir}/{tarball}.tar.{compression}" /> <echo msg="Hashvalue is; {filehashvalue}" /> ## C.11 FileSizeTask Stores the size of a specified file in a property. The file size is returned in bytes. Table C.12: Attributes NameTypeDescriptionDefaultRequired fileStringFilename.n/aYes propertynameStringName of property where the file size is stored.filesizeNo ### C.11.1 Example <filesize file="{builddir}/{tarball}.tar.{compression}" /> <php expression="floor({filesize}/1024)" returnProperty="ksize" /> <php expression="floor({filesize}/1024/1024)" returnProperty="msize" /> <echo msg="Filesize is: {ksize} kB"/> <echo msg="Filesize is: {msize} MB"/> ## C.12 FileSyncTask Syncs files or directories using the rsync command. Syncing can be done on the same server or from/to a remote server. Table C.13: Attributes NameTypeDescriptionDefaultRequired rsyncPathStringPath to rsync command./usr/bin/rsyncYes sourceDirStringSource directory (use [user@]host:path for remote sources).n/aYes destinationDirStringDestination directory (use [user@]host:path for remote destinations). Note: sub directories are created by default if they do not exist in the destination directory.n/aYes excludeStringExcluded file matching pattern. Use comma seperated values to exclude multiple files/directories, e.g.: a,bn/aNo excludeFileStringExcluded patterns file.n/aNo backupDirStringCreates a backup so users can rollback to an existing restore point.n/aNo optionsStringAny options that rsync supports, removes the default options. Should you wish to change the port ssh uses for remote transfers, set this attribute to -e 'ssh -p XXXXX' -rpKzl-rpKzNo verboseBooleanThis option increases the amount of information you are given during the transfer.TrueNo dryRunBooleanThis option makes rsync perform a trial run that doesn't make any changes.FalseNo itemizeChangesBooleanThis option requests a simple itemized list of the changes that are being made to each file, including attribute changes.FalseNo checksumBooleanThis option will cause rsync to skip files based on checksum, not mod-time & size.FalseNo deleteBooleanThis option deletes files that don't exist on sender after transfer including force and ignore-errors.FalseNo identityFileStringIdentity file for ssh authentication of a remote transfer.n/aNo ### C.12.1 Examples <filesync sourcedir="/var/www/development/project1" destinationdir="/var/www/project1" /> <filesync sourcedir="host::module" destinationdir="/var/www/project1/" /> <filesync sourcedir="/var/www/development/project1" destinationdir="user@server:/var/www/project1" dryrun="true" itemizechanges="true" verbose="true" checksum="true" /> In the sourcedir and destinationdir properties user name for remote connections is optional. ## C.13 FtpDeployTask Deploys a set of files to a remote FTP server. Table C.14: Attributes NameTypeDescriptionDefaultRequired hostStringThe hostname of the remote server.noneYes portIntegerThe port of the remote server.21No usernameStringThe username to use when logging in to the remote server.noneYes passwordStringThe password to use when logging in to the remote server.noneYes sslbooleanWhether to connect via SSL. This requires Net/FTP to be installed.falseNo dirStringDirectory on the remote server.noneNo modeStringThe transfer mode to use, either ascii or binary.binaryNo clearfirstBooleanDelete all files in the remote directory before uploading.falseNo passiveBooleanOpen connection in passive modefalseNo dirmodemixed Permissions of the uploaded files, can either be 'inherit' or it can be a octal value without the leading zero. Settings the dirmode to 'inherit' will cause the uploaded files to have the same permissions as on the filesystem. falseNo filemodemixedThis option does the same as dirmode, except it only affects regular files.falseNo dependsboolean If depends is set to true, the task will only update files with a local modification timestamp that is newer than the corresponding timestamp on the server. falseNo levelStringControl the level at which the task reports status messages. One of error, warning, info, verbose, debug.verboseNo rawdatafallbackboolean If Net_FTP is not able to parse the raw ftp data, the depends option does not work at all. Setting rawdatafallback will cause phing trying to parse the ftp data on its own, so the depends option might work again. If depends is set to false, rawdatafallback is ignored. No skiponsamesizeBooleanSkip upload, if file of same size exists.falseNo ### C.13.1 Example <ftpdeploy host="{ftp.host}" port="{ftp.port}" username="{ftp.username}" password="{ftp.password}" dir="{ftp.dir}" ssl="true" passive="false" mode="{ftp.mode}"> <fileset dir="."> <include name="**"/> <exclude name="phing"/> <exclude name="build.xml"/> <exclude name="images/**.png"/> <exclude name="images/**.gif"/> <exclude name="images/**.jpg"/> </fileset> </ftpdeploy> ### C.13.2 Supported Nested Tags • fileset The files to deploy ## C.14 GitBranchTask Create, move or delete repository branches. See official documentation (branch listing functionality is omitted in current implementation). Table C.15: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary./usr/bin/gitNo repositoryStringPath to Git repository.n/aYes branchnameStringThe name of the branch to create or delete.n/aYes newbranchStringThe new name for an existing branch.n/aYes, if branch move invoked startpointStringThe new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this option is omitted, the current HEAD will be used instead. See <start-point> argument of git-branch. No setupstreamStringIf specified branch does not exist yet or if --force has been given, acts exactly like --track. Otherwise sets up configuration like --track would when creating the branch, except that where branch points to is not changed. See --set-upstream option of git-branch. No trackBooleanSee --track option of git-branch.falseNo notrackBooleanSee --no-track option of git-branch.falseNo forceBooleanReset <branchname> to <startpoint> if <branchname> exists already. Without -f git branch refuses to change an existing branch.falseNo moveBooleanMove/rename a branch and the corresponding reflog.falseNo forcemoveBooleanMove/rename a branch even if the new branch name already exists.falseNo deleteBooleanDelete a branch. The branch must be fully merged in its upstream branch, or in HEAD if no upstream was set with --track or --set-upstream.falseNo forcedeleteBooleanDelete a branch irrespective of its merged status.falseNo ### C.14.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- Initialize normal repository --> <gitinit repository="{repo.dir.resolved}" /> <!-- Create branch "sample-branch" tracking current HEAD --> <gitbranch repository="{repo.dir.resolved}" branchname="sample-branch" /> <!-- Create branch "sample-branch" tracking origin/master Note that you can omit both startpoint and track attributes in this case --> <gitbranch repository="{repo.dir.resolved}" branchname="sample-branch" startpoint="origin/master" track="true" /> <!-- Delete fully merged branch "sample-branch" --> <gitbranch repository="{repo.dir.resolved}" branchname="sample-branch" delete="true" /> <!-- Force delete even unmerged branch "sample-branch" --> <gitbranch repository="{repo.dir.resolved}" branchname="sample-branch" forcedelete="true" /> <!-- Renabe "branch1" to "branch2" --> <gitbranch repository="{repo.dir.resolved}" branchname="branch1" newbranch="branch2" move="true" /> ## C.15 GitCheckoutTask Checkout a branch or paths to the working tree. See official documentation. Table C.16: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes branchnameStringBranch to checkout. See <branch> in git-checkout.originNo startpointStringThe name of a commit at which to start the new branch; Defaults to HEAD. See <start_point> in git-checkout. No createBooleanCreate a new branch named <branchname> and start it at <startpoint>falseNo forcecreateBooleanCreates the branch <branchname> and start it at <startpoint>; if it already exists, then reset it to <startpoint>. This is equivalent to running "git branch" with "-f".falseNo mergeBooleanSee --merge in git-checkout.falseNo trackBooleanSee --track in git-checkout.falseNo notrackBooleanSee --no-track in git-checkout.falseNo quietBooleanQuiet, suppress feedback messages. See --quiet in git-checkout.falseNo forceBooleanWhen switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes. See --force in git-checkout.falseNo ### C.15.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- create and switch to "mybranch" branch --> <gitcheckout repository="{repo.dir.resolved}" branchname="mybranch" quiet="true" create="true" /> <!-- get back to "master" branch --> <gitcheckout repository="{repo.dir.resolved}" branchname="master" quiet="true" /> <!-- create (force) already created branch --> <gitcheckout repository="{repo.dir.resolved}" branchname="mybranch" quiet="true" forceCreate="true" /> ## C.16 GitCloneTask Clone a repository into a new directory. Table C.17: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringThe (possibly remote) repository to clone from.n/aYes targetPathStringThe name of a new directory to clone into. Cloning into an existing directory is only allowed if the directory is empty.n/aYes bareBooleanCreate bare repository. See --bare option of git-clone.falseNo depthIntegerCreate a shallow clone with a history truncated to the specified number of revisions. See --depth option of git-clone.0No singleBranchBooleanClone only one branch. See --single-branch option of git-clone.falseNo branchStringCheckout branch instead of the remote's HEAD.n/aYes ### C.16.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- Clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- Clone bare repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" bare="true" /> ## C.17 GitCommitTask Record changes to the repository. See official documentation. Table C.18: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes messageStringCommit messagen/aNo allFilesBooleanWhether to automatically stage files that have been modified and deleted (see --all in git-commit)n/aNo ### C.17.1 Example <!-- commit all modified / deleted files -->; <gitcommit repository="/path/to/repo" message="Commit message" allFiles="true" />; ### C.17.2 Supported Nested Tags • fileset ## C.18 GitFetchTask Download objects and refs from another repository. See official documentation. Table C.19: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary./usr/bin/gitNo repositoryStringPath to Git repository.n/aYes sourceStringThe "remote" repository that is the source of a fetch or pull operation. See <repository> in git-fetch.originNo refspecStringSee <refspec> in git-fetch. No groupStringA name referring to a list of repositories as the value of remotes.<group> in the configuration file. See <group> in git-fetch. No quietBooleanSilence any internally used git commands. Progress is not reported to the standard error stream. See --quiet in git-fetch.falseNo allBooleanFetch all remotes. See --all in git-fetch.falseNo keepBooleanKeep downloaded pack. See --keep in git-fetch.falseNo pruneBooleanAfter fetching, remove any remote tracking branches which no longer exist on the remote. See --prune in git-fetch.falseNo tagsBooleanSee --tags in git-fetch.falseNo notagsBooleanSee --no-tags in git-fetch.falseNo forceBooleanWhen git fetch is used with <rbranch>:<lbranch> refspec, it refuses to update the local branch <lbranch> unless the remote branch <rbranch> it fetches is a descendant of <lbranch>. This option overrides that check. See --force in git-fetch.falseNo ### C.18.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- Initialize normal repository --> <gitinit repository="{repo.dir.resolved}" /> <!-- Fetch objects from all remotes --> <gitfetch repository="{repo.dir.resolved}" all="true" /> <!-- Fetch from origin/master to "refspec-branch" local branch --> <gitfetch repository="{repo.dir.resolved}" source="origin" refspec="master:refspec-branch" quiet="true" /> ## C.19 GitGcTask Cleanup unnecessary files and optimize the local repository. Table C.20: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary./usr/bin/gitNo repositoryStringThe repository to cleanup.n/aYes aggressiveBooleanThis option will cause git gc to more aggressively optimize the repository at the expense of taking much more time. See --aggressive option of git-gc.falseNo autoBooleanWith this option, git gc checks whether any housekeeping is required; if not, it exits without performing any work. See --auto option of git-gc.falseNo nopruneBooleanDo not prune any loose objects. See --no-prune option of git-gc.falseNo pruneStringPrune loose objects older than date. See --prune option of git-gc.2.weeks.agoNo ### C.19.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- Clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- Cleanup repository--> <gitgc repository="{repo.dir.resolved}" aggressive="true" prune="1.week.ago" /> ## C.20 GitInitTask Create an empty git repository or reinitialize an existing one. Table C.21: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes bareBooleanCreate bare repository. See --bare option of git-init.falseNo ### C.20.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- Initialize normal repository --> <gitinit repository="{repo.dir.resolved}" /> <!-- Initialize bare repository --> <gitinit bare="true" repository="{repo.dir.resolved}" /> ## C.21 GitLogTask Show commit logs. See official documentation. Table C.22: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes pathsString<paentry> arguments to git-log. Accepts one or more paths delimited by PATH_SEPARATORn/aNo outputPropertyStringProperty name to set with output value from git-logn/aNo formatStringCommit format. See --format of git-log. Can be one of oneline, short, medium, full, fuller, email, raw and format:<string>mediumNo dateStringDate format. See --date of git-log.n/aNo sinceString<since> argument to git-log.n/aNo untilString<until> argument to git-log.n/aNo statStringGenerate a diffstat. See --stat of git-logn/aNo nameStatusBooleanNames + status of changed files. See --name-status of git-log.falseNo maxCountIntegerNumber of commits to show. See -<n>|-n|--max-count of git-log.n/aNo noMergesBooleanDon't show commits with more than one parent. See --no-merges of git-log.falseNo ### C.21.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <gitlog paths="{repo.dir.resolved}" format="oneline" maxCount="2" stat="true" noMerges="false" since="Sun Jan 23 23:55:42 2011 +0300" until="Mon Jan 24 09:59:33 2011 +0300" outputProperty="logs" repository="{repo.dir.resolved}" /> ## C.22 GitMergeTask Join two or more development histories together. See official documentation. Table C.23: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes remoteStringSpace separated list of branches to merge into current HEAD. See <commit> in git-merge.n/aNo messageStringCommit message to be used for the merge commit (in case one is created). See <msg> in git-merge.n/aNo fastForwardCommitBooleanIf set false (default), will not generate a merge commit if the merge resolved as a fast-forward, only update the branch pointer. If set true, will generate a merge commit even if the merge resolved as a fast-forward. See --ff/--no-ff options in git-merge.falseNo strategyStringMerge strategy. One of "resolve", "recursive", "octopus", "ours", or "subtree". See <strategy> in git-merge.n/aNo strategyOptionStringPass merge strategy specific option through to the merge strategy. See <strategy-option> in git-merge.n/aNo commitBooleanSee --commit in git-merge.falseNo nocommitBooleanSee --no-commit in git-merge.falseNo quietBooleanQuiet, suppress feedback messages. See --quiet in git-merge.falseNo ### C.22.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- create couple of test branches --> <gitbranch repository="{repo.dir.resolved}" branchname="merge-test-1" startpoint="origin/master" /> <gitbranch repository="{repo.dir.resolved}" branchname="merge-test-2" startpoint="origin/master" /> <!-- Merge those branches back into master --> <gitmerge repository="{repo.dir.resolved}" remote="merge-test-1 merge-test-2" message="merging repos" commit="true" /> ## C.23 GitPullTask Fetch from and merge with another repository or a local branch. See official documentation. Table C.24: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes allBooleanFetch all remotesfalseNo sourceStringThe "remote" repository that is the source of a fetch or pull operation. See <repository> in git-pull.originYes, if allRemotes set to false refspecStringSee <refspec> in git-pull.n/aNo strategyStringMerge strategy. One of "resolve", "recursive", "octopus", "ours", or "subtree". See <strategy> in git-pull.n/aNo strategyOptionStringPass merge strategy specific option through to the merge strategy. See <strategy-option> in git-pull.n/aNo rebaseBooleanSee --rebase in git-pull.falseNo norebaseBooleanSee --no-rebase in git-pull.falseNo tagsBooleanEnable tag references following. See --tags in git-pull.falseNo notagsBooleanDisable tag references following. See --no-tags in git-pull.falseNo keepFilesBooleanSee --keep in git-pull.falseNo appendBooleanSee --append in git-pull.falseNo quietBooleanQuiet, suppress feedback messages. See --quiet in git-pull.falseNo forceBooleanForce update. See --force in git-pull.falseNo ### C.23.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- pull from all remotes --> <gitpull repository="{repo.dir.resolved}" all="true" /> <!-- pull remote origin/foobranch and rebase when merging --> <gitpull repository="{repo.dir.resolved}" source="origin" refspec="foobranch" strategy="recursive" keep="true" force="true" quiet="true" rebase="true" /> ## C.24 GitPushTask Update remote refs along with associated objects. See official documentation. Table C.25: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes allBooleanPush all referencesfalseNo destinationStringThe "remote" repository that is destination of a push operation. See <repository> in git-push.originYes, if allRemotes set to false refspecStringSee <refspec> in git-push.n/aNo mirrorBooleanSee --mirror in git-push.falseNo deleteBooleanDelete "remote" reference. Same as prefixing the refspec with colon. See --delete in git-push.falseNo tagsBooleanPush all references under refs/tags. See --tags in git-push.falseNo quietBooleanQuiet, suppress feedback messages. See --quiet in git-push.falseNo forceBooleanForce update. See --force in git-push.falseNo ### C.24.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <!-- push branch "master" into "foobranch" on "origin" remote --> <gitpush repository="{repo.dir.resolved}" refspec="master:foobranch" tags="true" /> <!-- create new branch "newbranch" on "origin" remote --> <gitpush repository="{repo.dir.resolved}" refspec="master:newbranch" quiet="true" /> <!-- delete "newbranch" branch from "origin" remote --> <gitpush repository="{repo.dir.resolved}" delete="true" refspec="newbranch" quiet="true" /> ## C.25 GitTagTask Create, list, delete or verify a tag object signed with GPG. See official documentation. Table C.26: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes messageStringUse given tag message. See -m of git-tag n/aNo nameStringTag namen/aYes commitString<commit> argument to git-tagn/aNo objectString<object> argument to git-tagn/aNo patternString<pattern> argument to git-tagn/aNo outputPropertyStringProperty name to set with output value from git-tagn/aNo fileStringTake tag message from given file. See -F of git-tag n/aNo annotateBooleanMake unsigned, annotated tag object. See -a of git-tag falseNo forceBooleanReplace existing tag with given name. See -f of git-tag falseNo deleteBooleanDelete existing tags with given names. See -d of git-tag falseNo listBooleanList tags with names matching given pattern. See -l of git-tag falseNo numIntegerSpecifies how many lines from the annotation, if any, are printed when using -l. See -n of git-tag n/aNo containsStringOnly list tags containing specified commit. See --contains of git-tag n/aNo signBooleanMake GPG-signed tag. See -s of git-tag falseNo keySignStringMake GPG-signed tag, using given key. See -u of git-tag of git-tag n/aNo verifyBooleanVerify GPG signature of given tag names. See -v of git-tag falseNo ### C.25.1 Example <property name="repo.dir" value="./relative/path/to/repo" /> <resolvepath propertyName="repo.dir.resolved" file="{repo.dir}" /> <!-- clone repository --> <gitclone repository="git://github.com/path/to/repo/repo.git" targetPath="{repo.dir.resolved}" /> <gittag repository="{repo.dir.resolved}" name="ver1.0" /> <!-- Force duplicate tag creation --> <gittag repository="{repo.dir.resolved}" name="ver1.0" force="true"/> <!-- Create tag with annotation and message --> <gittag repository="{repo.dir.resolved}" name="ver1.0" annotate="true" message="Version 1.0 tag"/> <!-- Delete tag --> <gittag repository="{repo.dir.resolved}" name="ver2.0" delete="true" /> <!-- List tags matching to pattern "marked" into "tags" variable --> <gittag repository="{repo.dir.resolved}" list="true" outputProperty="tags" pattern="marked" /> ## C.26 GitDescribeTask This task finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit. Table C.27: Attributes NameTypeDescriptionDefaultRequired gitPathStringPath to Git binary/usr/bin/gitNo repositoryStringPath to Git repositoryn/aYes outputPropertyStringProperty name to set with output value from git-describe.n/aNo allBooleanInstead of using only the annotated tags, use any ref found in refs/ namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag.falseNo tagsStringInstead of using only the annotated tags, use any tag found in refs/tags namespace. This option enables matching a lightweight (non-annotated) tag.falseNo containsBooleanInstead of finding the tag that predates the commit, find the tag that comes after the commit, and thus contains it. Automatically implies --tags.falseNo longBooleanAlways output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag.falseNo alwaysBooleanShow uniquely abbreviated commit object as fallback.falseNo abbrevIntegerInstead of using the default 7 hexadecimal digits as the abbreviated object name, use n digits, or as many digits as needed to form a unique object name. An n of 0 will suppress long format, only showing the closest tag.n/aNo matchStringOnly consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. This can be used to avoid leaking private tags from the repository.n/aNo committishStringCommit-ish object names to describe. Defaults to HEAD if omitted.HEADNo canditatesIntegerInstead of considering only the 10 most recent tags as candidates to describe the input commit-ish consider up to n candidates. Increasing n above 10 will take slightly longer but may produce a more accurate result. An n of 0 will cause only exact matches to be output.n/aNo ### C.26.1 Example <gitdescribe repository="{repo.dir}" tags="true" abbrev="0" match="*-*-*.*" outputProperty="mostRecentTag" /> ## C.27 GrowlNotifyTask When you have a long process and want to be notified when it is finished, without to stay focused on the console windows. Then use the GrowlNotify task. This task requires the PEAR Net_Growl package installed (version 2.6.0). Features • Compatible Windows and Mac/OSX • Do not forget notification with sticky option • Define priority of messages • Send notification on private or public network Table C.28: Attributes NameTypeDescriptionDefaultRequired nameStringName of application to be registerGrowl for PhingNo stickyBooleanIndicates if the notification should be sticky on desktopfalseNo messageStringText of notification. Use \n to specify a line breakn/aYes titleStringTitle of notificationGrowlNotifyNo notificationStringThe notification name/typeGeneral NotificationNo appiconString • absolute url (http://domain/image.png) • absolute file path (c:\temp\image.png) • relative file path (.\folder\image.png) n/aNo hostStringThe host address where to send the notification127.0.0.1No passwordStringThe password required to send notifications over networkn/aNo priorityString The notification priority. Valid values are : • low • moderate • normal • high • emergency normalNo protocolStringThe protocol used to send the notification. May be either gntp or udp.gntpNo iconString The icon to show for the notification. Must be a valid file type (png, jpg, gif, ico). Can be any of the following: • absolute url (http://domain/image.png) • absolute file path (c:\temp\image.png) • relative file path (.\folder\image.png) embedded growl icon v2No ### C.27.1 Examples Send a single notification on a remote host Both sender and Growl client (Mac or Windows) should share the same password. <?xml version="1.0" encoding="UTF-8"?> <project name="phing-GrowlNotifyTask" basedir="." default="notification"> <taskdef name="growlnotify" classname="phing.tasks.ext.GrowlNotifyTask" /> <target name="notification" description="display a single message with growl gntp over network" > <growlnotify message="Deployment of project LAMBDA is finished." host="192.168.1.2" password="seCretPa$$word"
/>
</target>

</project>

Send a single notification with UDP protocol

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

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

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

</project>

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

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

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

</project>

Use your icons to identify an application

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

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

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

</project>

Add files to Mercurial repository on the next commit. This is available for PHP 5.4 and higher.

Table C.29: Attributes

NameTypeDescriptionDefaultRequired
repositoryStringPath to Mercurial repository.n/aYes

### C.28.1 Example

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

### C.28.2 Supported Nested Tags

• fileset

Create an unversioned archive of a Mercurial repository revision. This is available for PHP 5.4 and higher.

Table C.30: Attributes

NameTypeDescriptionDefaultRequired
destinationStringName of archive to create.n/aYes
revisionStringRevision to distribute in the archive.n/aNo

### C.29.1 Example

<property name="version" value="v0_1_2"/>
<hgarchive destination="${version}.zip" /> <hgarchive destination="${version}.tgz" />

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" />
<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.34.1 Example <hgpull quiet="false" insecure="true" repository="${repo.dir}"/>

Push changes from the local Mercurial repository to the specified destination. This is available for PHP 5.4 and higher.

Table C.36: Attributes

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

### C.35.1 Example

<property name="repo.dir" value="./repo.directory" />
<hgpush haltonerror="true" repository="{repo.dir.resolved}"/> 

Revert files to their checkout state from the Mercurial repository. This is available for PHP 5.4 and higher.

Table C.37: Attributes

NameTypeDescriptionDefaultRequired
allBooleanRevert all Changes when no other details are given.falseNo
nameStringName of file to revert.n/aNo
quietBooleanWork silently unless an error occurs.falseNo
revisionStringRevision to revert to.n/aNo

### C.36.1 Example

<hgrevert all="true"/>

Add a tag for the current or specified revision of the local Mercurial repository. This is available for PHP 5.4 and higher.

Table C.38: Attributes

NameTypeDescriptionDefaultRequired
messageStringMessage to add/edit tag with.n/aNo
nameStringName of tag.n/aYes
repositoryStringPath to Mercurial repository.n/aNo
revisionStringRevision to tag.n/aNo
userStringUser to record as the committer.n/aNo

### C.37.1 Example

<hgtag user="phingbot" message="tagging new release" name="v0.1.2"/>

Update the Mercurial repository's working directory or switch revisions. This is available for PHP 5.4 and higher.

Table C.39: Attributes

NameTypeDescriptionDefaultRequired
branchStringA specific branch to pull.n/aNo
cleanBooleanDiscard uncommitted changes.falseNo
quietBooleanWork silently unless an error occurs.falseNo
repositoryStringPath to Mercurial repository.n/aYes

### C.38.1 Example

<property name="repo.dir" value="./repo.directory" />
<hgupdate repository="${repo.dir.resolved}" branch="dev"/>  ## 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" dest="${project.basedir}/application/configs/application.ini">
<set section="production" property="buildTimestamp" value="${DSTAMP}${TSTAMP}" />
<set section="production" property="buildNumber" operation="+" />
<remove section="development : staging" />
</inifile>

The IoncubeEncoderTask executes the ionCube encoder (for either PHP4 or PHP5 projects).

Table C.50: Attributes

NameTypeDescriptionDefaultRequired
allowedserverStringRestricts the encoded files to particular servers and/or domains. Consult the IonCude documentation for more information.noneNo
binaryBooleanWhether to save encoded files in binary format (default is ASCII format)falseNo
copyStringSpecifies files or directories to exclude from being encoded or encrypted and copy them to the target directory (separated by space).noneNo
encodeStringSpecifies additional file patterns, files or directories to encode, or to reverse the effect of copynoneNo
encryptStringSpecify files or directories (space separated list) that are to be encrypted.noneNo
expireinStringSets a period in seconds (s), minutes (m), hours (h) or days (d) after which the files expire. Accepts: 500s or 55m or 24h or 7dnoneNo
expireonStringSets a YYYY-MM-DD date to expire the files.noneNo
fromdirStringPath containing source filesnoneYes
ignoreStringSet files and directories to ignore entirely and exclude from the target directory (separated by space).noneYes
ioncubepathStringPath to the ionCube binaries/usr/local/ioncubeNo
keepStringSet files and directories not to be ignored (separated by space).noneNo
licensepathStringPath to the license file that will be used by the encoded filesnoneNo
nodoccommentsStringOmits documents comments ( /** ... */ ) from the encoded files.noneNo
obfuscationkeyStringThe obfuscation key must be supplied when using the obfuscate optionnoneNo
obfuscateStringThe Encoder can obfuscate the names of global functions, the names of local variables in global functions, and line numbers. Use either all or any of functions, locals or linenos separated by a space.noneNo
optimizeStringControls the optimization of the encoded files, accepts either more or maxnoneNo
passphraseStringThe passphrase to use when encoding with a license filenoneNo
phpversionIntegerThe PHP version to use5No
targetoptionStringOption to use when target directory exists, accepts replace, merge, update and renamenoneNo
todirStringPath to save encoded files tononeYes
withoutruntimeloadersupportBooleanWhether to disable support for runtime initialization of the ionCube LoaderfalseNo
noshortopentagsBooleanWhether to disable support for short PHP tagsfalseNo
callbackfileStringPath to callback file (.php)n/aNo
obfuscationexclusionsfileStringPath to obfuscation exclusions filen/aNo
ignoredeprecatedwarningsBooleanWhether to ignore deprecated warningsfalseNo
ignorestrictwarningsBooleanWhether to ignore strict warningsfalseNo
allowencodingintosourceBooleanWhether to allow encoding into the source treefalseNo
messageifnoloaderStringA valid PHP expression to customize the "no loader installed" messagen/aNo
actionifnoloaderStringA valid PHP expression to replace the "no loader installed" actionn/aNo
showcommandlineBooleanwhether to show command line before it is executedfalseNo

### C.42.1 Example

<ioncubeencoder
binary="true"
copy="*.ini config/*"
encrypt="*.tpl *.xml"
fromdir="files"
ignore="*.bak RCS/ *~ docs/"
ioncubepath="/usr/local/ioncube"
optimize="max"
passphrase="mypassphrase"
phpversion="4"
noshortopentags="false"
targetoption="replace"
todir="encoded"
callbackfile="errhandler.php"
obfuscationexlusionsfile="obfex.txt">
<comment>A project encoded with the ionCube encoder.</comment>
</ioncubeencoder>

### C.42.2 Supported Nested Tags

• comment

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

The IoncubeLicenseTask executes the ionCube make_license program.

Table C.51: Attributes

NameTypeDescriptionDefaultRequired
ioncubepathStringPath to the ionCube binaries/usr/local/ioncubeNo
licensepathStringPath to the license file that will be generatednoneNo
passphraseStringThe passphrase to use when generating the license filenoneNo
allowedserverStringRestricts the license to particular servers and/or domains. Consult the IonCude documentation for more information.noneNo
expireinStringSets a period in seconds (s), minutes (m), hours (h) or days (d) after which the license expires. Accepts: 500s or 55m or 24h or 7d.noneNo
expireonStringSets a YYYY-MM-DD date to expire the license.noneNo

### C.43.1 Example

<ioncubelicense
ioncubepath="/usr/local/ioncube"
passphrase="mypassphrase"
allowedserver="00:06:4F:01:8F:2C"
expireon="2010-09-01"
expirein="7d">
</ioncubelicense>

### C.43.2 Supported Nested Tags

• comment

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

This task runs JSHint, a tool that helps to detect errors and potential problems in JavaScript code. JSHint 2.5.6+ is supported, although latest JSHint is recommended.

Table C.52: Attributes

NameTypeDescriptionDefaultRequired
fileStringSingle file to perform check on.n/aNo, unless no fileset elements are present
haltOnErrorbooleanShould the build fail when there are errors in the JS code?falseNo
haltOnWarningbooleanShould the build fail when there are warnings in the JS code?falseNo
reporterStringJSHint reporter.checkstyleNo
checkstyleReportPathStringPath where the the report in Checkstyle format should be saved.n/aNo
configStringJSHint config path.n/aNo

### C.44.1 Example

        <jshint
haltonerror="false"
haltOnWarning="false"
reporter="jslint"
checkstyleReportPath="${project.basedir}/build/checkstyle-jshint.xml"> <fileset dir="${project.basedir}/public_html/www/js">
<include name="**/**.js"/>
<exclude name="js-cache/**"/>
</fileset>
</jshint>

### C.44.2 Supported Nested Tags

• fileset

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

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

Table C.53: Attributes

NameTypeDescriptionDefaultRequired
executableStringPath to JSL executablejslNo
fileStringPath to source filen/aNo, unless no fileset elements are present
haltonfailureBooleanStop the build process if the linting process encounters an error.falseNo
haltonwarningBooleanStop the build process if the linting process encounters a warning.falseNo
showwarningsBooleanSets the flag if warnings should be shown.trueNo
cachefileStringIf set, enables writing of last-modified times to cachefile, to speed up processing of files that rarely changenoneNo
conffileStringPath to JSL config filenoneNo
tofileStringFile to write list of 'bad files' to.n/aNo

### C.45.1 Example

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

Checking syntax of one particular source file.

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

Check syntax of a fileset of source files.

### C.45.2 Supported Nested Tags

• fileset

The JsMinTask minifies JavaScript files using JShrink, which can be installed using composer (Phing will try to use the composer autoloader)

Table C.54: Attributes

NameTypeDescriptionDefaultRequired
targetDirStringPath where to store minified JavaScript filesnoneYes
suffixStringSuffix to append to the filenames.-minNo
failonerrorBooleanWhether an error while minifying a JavaScript file should stop the build or notfalseNo

### C.46.1 Example

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

### C.46.2 Supported Nested Tags

• fileset

JavaScript files to be minified.

The LiquibaseTask is a generic task for liquibase commands that don't require extra command parameters. You can run commands like updateSQL, validate or updateTestingRollback with this task but not rollbackToDateSQL since it requires a date parameter after the command.

Table C.55: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
commandStringWhat liquibase command to run. Currently only supports commands that doesn't require command parameters, such as validate and updateSQL.n/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.47.1 Example

            <liquibase
jar="./vendor/alcaeus/liquibase/liquibase.jar"
classpathref="./libs/mysql-connector-java.jar"
changelogFile="./DB/master.xml"
username="${deploy.user}" password="${deploy.password}"
url="jdbc:mysql://${database.host}/${database.name}"
display='true'
checkreturn="true"
passthru='false'
>
<parameter name="logLevel" value="info" />
<property name="tablename" value="Person" />
</liquibase>


The nested parameters in the example above will result in the command:

    --logLevel='info' updateSQL -Dtablename='Person'


### C.47.2 Supported Nested Tags

• parameter

Use these nested parameter tags to set optional liquibase commands like --logLevel or --defaultsFile.

Table C.56: Attributes

NameTypeDescriptionDefaultRequired
nameStringName of the liquibase parameter. Do not include the '--'.n/aYes
valueStringValue of the liquibase parameter.n/aYes

• property

These tags are used to set what Liquibase calls "Change Log Properties" which are used for substitution in the change log(s). Note that they are not the same thing as regular Phing properties.

Table C.57: Attributes

NameTypeDescriptionDefaultRequired
nameStringName of the property. Do not include the '-D'.n/aYes
valueStringValue of the property.n/aYes

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

Table C.58: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.48.1 Example

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

### C.48.2 Supported Nested Tags

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

Table C.59: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC URL representing the database data source, e.g jdbc:mysql://localhost/mydatabasen/aYes
outputDirStringAbsolute path where the documentation gets written to. If the given directory does not exist, it gets created automatically.n/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.49.1 Example

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

### C.49.2 Supported Nested Tags

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

Table C.60: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
referenceUsernameStringThe username needed to connect to the reference database.n/aYes
referencePasswordStringThe password needed to connect to the reference database.n/aYes
referenceUrlStringThe JDBC Url representing the database reference datasource, e.g jdbc:mysql://localhost/refdatabasen/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.50.1 Example

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

### C.50.2 Supported Nested Tags

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

Table C.61: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
rollbackTagStringThe name of the tag to roll the database back to.n/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.51.1 Example

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

### C.51.2 Supported Nested Tags

The LiquibaseTagTask tags the current database state for future rollback.

Table C.62: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
tagStringThe name of the tag to apply.n/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.52.1 Example

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

### C.52.2 Supported Nested Tags

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

Table C.63: Attributes

NameTypeDescriptionDefaultRequired
jarStringLocation of the Liquibase jar file.n/aYes
classpathStringAdditional classpath entries.n/aYes
changeLogFileStringLocation of the changelog file in which the changes get written or read from.n/aYes
usernameStringThe username needed to connect to the database.n/aYes
passwordStringThe password needed to connect to the database.n/aYes
urlStringThe JDBC Url representing the database datasource, e.g jdbc:mysql://localhost/mydatabasen/aYes
displayBooleanWhether to display the output of the command. Only used if passthru isn't true.falseNo
passthruBooleanWhether to use PHP's passthru() function instead of exec(). True by default for backwards compatibility. When true, the attributes display, outputProperty and checkReturnare ignored.trueNo
checkreturnBooleanWhether to check the return code of the execution, throws a BuildException when returncode != 0.falseNo
outputPropertyStringProperty name to set output value to from the execution. Ignored if passthru attribute is true.n/aNo

### C.53.1 Example

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

### C.53.2 Supported Nested Tags

A task to send email. Attachments are supported if the PEAR Mail package is installed.

Table C.64: Attributes

NameTypeDescriptionDefaultRequired
fromStringEmail address of sender.noneYes
tolistStringComma-separated list of recipients.noneYes
messageStringMessage to send in the body of the email.noneNo
subjectStringEmail subject line.noneNo
backendStringPEAR Mail backend (see here for possible values).mailNo
backendParamsStringComma-separated key-value pairs with backend specific parameters (see here for possible values).noneNo

### C.54.1 Example

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

### C.54.2 Supported Nested Tags

• fileset

Files to be attached.

This task generates a simple manifest file with optional checksums.

Table C.65: Attributes

NameTypeDescriptionDefaultRequired
saltStringSalt to use when generating checksums.n/aNo
checksumStringComma separated list of checksums (hashing algorithms) to run, or false to disable checksum generation. Possible values are md5, crc32 or any of the algorithms returned by hash_algos().falseNo
fileStringThe path to the manifest file.n/aYes.

### C.55.1 Supported Nested Tags

• fileset

This is a wrapper for notify-send, for displaying desktop notifications locally.

Table C.66: Attributes

NameTypeDescriptionDefaultRequired
iconstringSpecify an icon filename or stock icon to display.infoNo
messageStringText to display. Use \n to specify a line breakn/aYes
titleStringTitle, or summary, of the notification.noneNo

Converts dot-notation packages to relative paths and stores it in a property.

Table C.67: Attributes

NameTypeDescriptionDefaultRequired
packageStringThe package to convert.n/aYes
nameStringThe property to store the path in.n/aYes

### C.57.1 Example

Sample build command:

<packageaspath package="phing.classes" name="path"/>

Parallel tasks have a number of uses in a Phing build file including:

• Taking advantage of available processing resources to execute external programs simultaneously.

• Testing servers, where the server can be run in one thread and the test harness is run in another thread.

While the tasks within the parallel task are being run, the main thread will be blocked waiting for all the child threads to complete. If one of the tasks within the parallel task fails, the remaining tasks will continue to run until all tasks have completed. In this situation, the parallel task will also fail.

The threadCount attribute can be used to place a maximum number of available threads for the execution. When not present the value is based on the number of processors present. When present then the maximum number of concurrently executing tasks will not exceed the number of threads specified. Furthermore, each task will be started in the order they are given. But no guarantee is made as to the speed of execution or the order of completion of the tasks, only that each will be started before the next.

### Warning

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

Table C.68: Attributes

NameTypeDescriptionDefaultRequired
threadCountIntegerMaximum number of threads / processes to use.n/aNo

### C.58.1 Example

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

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

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

Table C.69: Attributes

NameTypeDescriptionDefaultRequired
patchfileStringFile that includes the diff outputn/aYes
originalfileStringFile to patch. If not specified Task tries to guess it from the diff filenoneNo
destfileStringFile to send the output to instead of patching the file in placenoneNo
backupsBooleanKeep backups of the unpatched filesfalseNo
quietBooleanWork silently unless an error occursfalseNo
reverseBooleanAssume patch was created with old and new files swappedfalseNo
ignorewhitespaceBooleanIgnore whitespace differencesfalseNo
stripIntegerStrip the smallest prefix containing specified number of leading slashes from filenamesnoneNo
dirStringThe directory in which to run the patch commandnoneNo
haltonfailureBooleanStop the build process if the patching process encounters an error.falseNo

### C.59.1 Example

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

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

Coverts a path to a fileset. This is useful if you have a path but need to use a fileset as input in a phing task.

Table C.70: Attributes

NameTypeDescriptionDefaultRequired
dirStringThe root of the directory tree of this FileSet.n/aYes
pathrefidStringThe reference to the path to convert from.n/aYes
ignorenonrelativeBooleanThis boolean controls what will happen if any of the files in the path are not in the directory for the fileset. If this is "true" the files are ignored, if this is "false" a build exception is thrown. (Note: if files are not present no check is made).falseNo
nameStringThis is the identifier of the fileset to create. This fileset will contain the files that are relative to the directory root. Any files that are not present will not be placed in the set.n/aYes

### C.60.1 Examples

<path id="modified.sources.path" dir="C:\Path\to\phing\classes\phing\" />
<pathtofileset name="modified.sources.fileset"
pathrefid="modified.sources.path"
dir="." />

<copy todir="C:\Path\to\phing\docs\api">
<mapper type="glob" from="*.php" to="*.php.bak" />
<fileset refid="modified.sources.fileset" />
</copy>

The PDOSQLExecTask executes SQL statements using PDO.

### Note

The combination of large SQL files and delimitertype set to normal can trigger segmentation faults with large files.

Table C.71: Attributes

NameTypeDescriptionDefaultRequired
urlStringPDO connection URL (DSN)noneYes
useridStringUsername for connection (if it cannot be specified in URL) noneNo
passwordStringThe password to use for the connection (if it cannot be specified in URL)noneNo
srcFileA single source file of SQL statements to execute.noneNo
onerrorStringThe action to perform on error (continue, stop, or abort)abortNo
delimiterStringThe delimiter to separate SQL statements (e.g. "GO" in MSSQL);No
delimitertypeStringThe delimiter type ("normal", "row" or "none"). Normal means that any occurrence of the delimiter terminate the SQL command whereas with row, only a line containing just the delimiter is recognized as the end of the command. None disables all delimiter detection.noneNo
autocommitBooleanWhether to auto (implicitly) commit every single statement, disabling transactions.falseNo
encodingStringEncoding to use for read SQL filesnoneNo

### C.61.1 Example

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

### Note

Because of backwards compatibility, the PDOSQLExecTask can also be called using the 'pdo' statement.

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

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

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

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

### C.61.2 Supported Nested Tags

• transaction

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

Table C.72: Attributes

NameTypeDescriptionDefaultRequired
srcStringFile with statements to be run as one transactionn/aNo

• fileset

Files containing SQL statements.

• filelist

Files containing SQL statements.

• formatter

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

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

Table C.73: Attributes

NameTypeDescriptionDefaultRequired
typeStringUse a predefined formatter (either xml or plain). n/aOne of these attributes is required.
classnameStringName of a custom formatter class (must extend phing.tasks.ext.pdo.PDOResultFormatter).n/a
usefileBooleanBoolean that determines whether output should be sent to a file.trueNo
outfileFilePath to file in which to store result.Depends on formatterNo
showheadersBoolean(only applies to plain formatter) Whether to show column headers.falseNo
coldelimString(only applies to plain formatter) The column delimiter.,No
rowdelimString(only applies to plain formatter) The row delimiter.\nNo
encodingString(only applies to XML formatter) The xml document encoding.(PHP default)No
formatoutputBoolean(only applies to XML formatter) Whether to format XML output.trueNo

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

### Note

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

This task uses the PEAR_PackageFileManager class. In order to be maximally flexible, the majority of options are set generically (using <option> tag) and are set using PEAR_PackageFileManager::setOptions() . Use the <mapping> tag to represent complex values (which are turned into associative arrays and also set using setOptions() method).

Table C.74: Attributes

NameTypeDescriptionDefaultRequired
nameStringThe name of the PEAR package.n/aYes
dirStringThe base directory of files to add to package.n/aYes
destFileStringThe file to create.package.xml in base directoryNo

### C.62.1 Example

<pearpkg name="phing" dir="${build.src.dir}" destFile="${build.base.dir}/package.xml">
<fileset dir=".">
<include name="**"/>
</fileset>
<option name="notes">Sample release notes here.</option>
<option name="description">Package description</option>
<option name="summary">Short description</option>
<option name="version" value="2.0.0b1"/>
<option name="state" value="beta"/>
<mapping name="maintainers">
<element>
<element key="handle" value="hlellelid"/>
<element key="name" value="Hans"/>
<element key="email" value="hans@xmpl.org"/>
</element>
</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

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

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

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>
<element name="version" value="1.0" />
<element name="authors">
<element name="John Doe">
<element name="e-mail" value="john@example.com" />
</element>
</element>
</pharpackage>

### C.65.2 Supported Nested Tags

• fileset

• metadata

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.

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.

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

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

Table C.97: Attributes

NameTypeDescriptionDefaultRequired
typeStringThe name of the analyzer. Valid analyzers are: coderank-mode.n/aYes
valueStringThe value for the analyzer.n/aYes

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.98: Attributes

NameTypeDescriptionDefaultRequired
titleStringTitle of the project.n/aNo
destdirStringDestination directory for output files.n/aYes
templateStringName of the documentation template to use.responsive-twigNo
defaultPackageNameStringName of the default package.DefaultNo
pharlocationStringLocation of the phpDocumentor PHAR package.n/aNo

### C.72.1 Example

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

### C.72.2 Supported Nested Tags

• fileset - Files that should be included for parsing

The PhpLintTask checks syntax (lint) on one or more PHP source code files.

Table C.99: 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.73.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.73.2 Supported Nested Tags • fileset ## C.74 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! Table C.100: 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.74.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.101: 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.102: 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.74.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.74.3 Supported Nested Tags • fileset ## C.75 PHPUnitReport This task transforms PHPUnit xml reports to HTML using XSLT. Table C.103: 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.75.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.76 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.104: 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.76.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.76.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.76.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}"/>

Replaces the occurrences of a given regular expression with a substitution pattern in a selected file or set of files.

Table C.105:

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.77.1 Supported Nested Tags

• fileset

Renders rST (reStructuredText) files into different output formats.

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

Table C.106: 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.78.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.78.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="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="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="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.78.3 Supported Nested Tags

• fileset

• mapper

• filterchain

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

Table C.107: 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.79.1 Example

<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.79.2 Supported Nested Tags • fileset ## C.80 S3GetTask Downloads an object from Amazon S3. This task requires the PEAR package Services_Amazon_S3 Table C.108: 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.80.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.81 SassTask The SassTask converts SCSS or Sass files to CSS using either the 'sass' gem or the scssphp package. Table C.109: 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. ### C.81.1 Example <sass style="compact" trace="yes" unixnewlines="yes" outputpath="${compiled.dir.resolved}">
<fileset dir="."/>
</sass>

### C.81.2 Supported Nested Tags

• fileset

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

Table C.110: 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.82.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.82.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.111: 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.83 SmartyTask A task for generating output by using Smarty. Table C.112: 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.84 SonarTask This task runs SonarQube Scanner, a tool for code analysis and continuous inspection. Table C.113: Attributes NameTypeDescriptionDefaultRequired executableStringFully-qualified path of SonarQube Scanner executable. If executable is in PATH environment variable, the executable name is sufficient.n/aYes configurationStringPath of configuration file. The file format is that of a properties file (as used by Java), i.e. a list of key-value pairs <key>=<value>.n/aNo errorsStringSets errors flag of SonarQube Scanner. Allowed values are "true", "false", "yes", "no", "1", and "0".falseNo debugStringSets debug flag of SonarQube Scanner. Allowed values are "true", "false", "yes", "no", "1", and "0".falseNo ### C.84.1 Examples #### Minimal Example This example assumes that the SonarQube Scanner is called sonarqube-scanner and is available on the PATH. <?xml version="1.0" encoding="UTF-8"?> <project name="sonar-minimal-example" default="sonar"> <taskdef name="sonar" classname="phing.tasks.ext.sonar.SonarTask" /> <sonar executable="sonarqube-scanner"> <property name="sonar.projectKey" value="my-unique-project-key" /> <property name="sonar.projectName" value="Foo Project" /> <property name="sonar.projectVersion" value="0.1.0" /> <property name="sonar.sources" value="src" /> </sonar> </project> #### Full Example This example consists of two files – build.xml and sonar-project.properties. The build.xml: <?xml version="1.0" encoding="UTF-8"?> <project name="sonar-full-example" default="sonar"> <taskdef name="sonar" classname="phing.tasks.ext.sonar.SonarTask" /> <sonar executable="path/to/sonarqube-scanner" errors="true" debug="true" configuration="path/to/sonar-project.properties" > <!-- Assume that mandatory SonarQube parameters are defined in configuration file! --> <property name="sonar.log.level" value="DEBUG" /> </sonar> </project> The configuration file path/to/sonar-project.properties: sonar.projectKey = my-unique-project-key sonar.projectName = Foo Project sonar.projectVersion = 0.1.0 sonar.sources = src ### C.84.2 Supported Nested Tags • property Analysis parameters of SonarQube Scanner can be defined in a configuration file or via nested property elements. If both a configuration file and property elements are provided, the properties are merged. Values from property elements overwrite values from the configuration file if their property keys are equal. Table C.114: Attributes NameTypeDescriptionDefaultRequired nameStringName of property.n/aYes valueStringValue of property.n/aYes ## C.85 SshTask The SshTask executes commands on a remote host using ssh. This task requires the PHP SSH2 extension to function. Table C.115: 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.85.1 Example <ssh username="john" password="smith" host="webserver" command="ls" /> Executes a single command on the remote server. ### C.85.2 Supported Nested Tags • 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.116: 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

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

Table C.117: Attributes

NameTypeDescriptionDefaultRequired
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.86.1 Example

<svncheckout
svnpath="/usr/bin/svn"
nocache="true"
repositoryurl="svn://localhost/project/trunk/"
todir="/home/user/svnwc"/>
<svncheckout
svnpath="C:/Subversion/bin/svn.exe"
repositoryurl="svn://localhost/project/trunk/"
todir="C:/projects/svnwc"/>

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

Table C.118: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
usernameStringA username used to connect to the SVN servernoneNo
passwordStringA password used to connect to the SVN servernoneNo
nocacheBooleanConnection credentials will not be cachedfalseNo
depthStringLimit operation by depthempty, files, immediates or infinityNo
workingcopyStringWorking copynoneYes
messageStringThe commit messagenoneYes
ignoreexternalsBooleanIgnore externals definitionsfalseNo
trustServerCertBooleanTrust self-signed certificatesfalseNo
propertynameStringName of property to set to the last committed revision numbersvn.committedrevisionNo

### C.87.1 Example

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

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

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

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

Table C.119: 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.88.1 Example

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

The SvnExportTask exports a Subversion repository to a local directory.

Table C.120: 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.89.1 Example

<svnexport
svnpath="/usr/bin/svn"
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"/>

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

Table C.121: 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.90.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"/>

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

Table C.122: 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

### C.91.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"/>

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.123: 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
limitIntegerLimits the number of items to get back from the commandn/aNo
orderDescendingBooleanSets whether to reverse the order of the listed itemsfalseNo

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

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.124: 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
limitIntegerLimits the number of items to get back from the commandn/aNo

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

The SvnUpdateTask updates a local directory.

Table C.125: Attributes

NameTypeDescriptionDefaultRequired
svnpathStringPath to Subversion binary/usr/bin/svnNo
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 the working copynoneYes
revisionIntegerSpecific revision to update the working copy tononeNo
ignoreexternalsBooleanIgnore externals definitionsfalseNo
trustServerCertBooleanTrust self-signed certificatesfalseNo

### C.94.1 Example

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

The SvnSwitchTask changes a local directory from one repository to another.
svnpathStringPath to Subversion binary/usr/bin/svnNo
repositoryurlStringURL of remote repositorynoneYes
todirStringPath to the checked out projectnoneYes
usernameStringA username used to connect to the SVN servernoneNo
passwordString`A password used to connect to the SVN servernoneN