Putting Phing to Work for You
Hans Lellelid
International PHP Conference
2007-11-05

Introduction
• My name is Hans Lellelid
• Developer & Manager at Applied Security,
Inc. (near Washington DC).
• PHP developer and OO evangelist.
• I ported Phing to PHP5 in 2004.
• I now manage the Phing project with
Michiel Rook.
Hans Lellelid: Putting Phing to Work for You 2

What is it?
• PHing Is Not Gnumake
• It is a project build tool.
• Original PHP4 version by Andreas Aderhold
• Written for PHP5
• Based on Apache Ant
• Cross-platform (i.e. Windows too)
• http://phing.info/
Hans Lellelid: Putting Phing to Work for You 3

Workshop Topics: Fundamentals
• Phing basics
• Creating a first build file
• Transforming directories and files
• Performing PDO tasks
• Gathering user input
• Building phpdoc
• Running unit tests
• Integrating with CI tools
Hans Lellelid: Putting Phing to Work for You 4

Workshop Topics: Extension
• Using PHP code in a build file
• Building a simple Task
• Writing more complex Task
• Creating a shared Type
• Custom filters
• Custom selectors
• Custom logger/listener
• Custom input handlers
Hans Lellelid: Putting Phing to Work for You 5

Getting Started
Hans Lellelid: Putting Phing to Work for You 6

Install Phing
• Install via PEAR
– pear channel-discover pear.phing.info
– pear install phing/phing
• Install “traditional” package
– Available on Download page
• Install from SVN
– svn co http://svn.phing.info/trunk phing
Hans Lellelid: Putting Phing to Work for You 7

Following Along
• Install via PEAR
– pear install phing/phing
– Install “traditional” package
• Available on Download page
– Install from SVN
• svn co http://svn.phing.info/trunk phing
Hans Lellelid: Putting Phing to Work for You 8

The phing script
• A wrapper shell script for phing.php script.
• Sets default logger to use (dependent on
system)
• Typical usage: phing [target]
• Other useful options:
– Help (-h)
– Specify properties (-Dpropname=value)
– List targets (-l)
– Get more output (-verbose or -debug)
Hans Lellelid: Putting Phing to Work for You 9

Buildfiles
• Build files are XML
• Build files are composed of:
– Tasks: a “build-in” piece of code that a
specific function. E.g. <mkdir>
– Types: data structures that are used
commonly by tasks. E.g. <path>
– Targets: grouping of Tasks that perform a
more general function. E.g. Copy files to a
new directory.
– A Project: the root node for the build file.
Hans Lellelid: Putting Phing to Work for You 10

A simple build file
<project name=\"sample\" default=\"main\">
<property name=\"ver\" value=\"1.0.1\"/>
<property file=\"build.properties\"/>
<target name=\"main\">
<mkdir dir=\"./build/${ver}\">
<copy todir=\"./build/${ver}\">
<fileset dir=\".\"
includes=\"*.txt\" />
</copy>
</target>
</project>
Hans Lellelid: Putting Phing to Work for You 11

Javaisms
• Properties
– Properties are variables for build scripts.
– Like php.ini, but more flexible:
• tgz = ${pkg}-${ver}.tgz
– Can be set in build script or imported from
files.
• Dot-path notation for class names:
– path.to.Class = path/to/Class.php
– Represents directory and class name in a
single string.
Hans Lellelid: Putting Phing to Work for You 12

Control Structures
• depends, if, and unless attributes provide
control over target execution condition and
sequence.
• <if> task provides a more familiar (to
developers) control structure that can be
used within a target.
Hans Lellelid: Putting Phing to Work for You 13

Reorganize, Transform
Hans Lellelid: Putting Phing to Work for You 14

Match a bunch of files
• The <fileset> type represents an
extremely powerful way to select a
group of files for processing
• Many built-in tasks support <fileset>
Hans Lellelid: Putting Phing to Work for You 15

Fileset Examples
<fileset dir=\"./webapp\"
includes=\"**/*.html\"
excludes=\"**/test-*\"/>
<fileset dir=\"./webapp\">
<include name=\"img/${theme}/*.jpg\"/>
<include name=\"tpl/${lang}/*.phtml\"/>
<exclude name=\"**/*.bak\"/>
<exclude name=\"**/test/**\"/>
</fileset>
Hans Lellelid: Putting Phing to Work for You 16

Fine-tuned Selection
• Selectors provide entirely new dimensions
for <fileset> file matching criteria.
• Some examples of selectors:
– Created before/after certain date
– Greater/less than specified size
– Type ('file' or 'dir')
– At specific depth in dir structure
– Having corresponding file in another dir.
Hans Lellelid: Putting Phing to Work for You 17

Selector examples
<fileset dir=\"${htdocs.dir}\">
<includes name=”**/*.html”/>
<containsregexp
expression=\"/prod\\d+\\.php\"/>
</fileset>
<fileset dir=\"${dist}\" includes=\"**\">
<or>
<present targetdir=\"${htdocs}\"/>
<date datetime=\"01/01/2007\"
when=\"before\"/>
</or>
</fileset>
Hans Lellelid: Putting Phing to Work for You 18

Filesystem Transformations
• The <mapper> element adds filesystem
transformation capabilities to supporting
tasks (e.g. <copy>, <move>).
• For example:
– Change all “.php” files to “.html”
– Remove dirs from filename
– Change all files to the same filename
• Custom mappers can be defined.
Hans Lellelid: Putting Phing to Work for You 19

Mapper examples
<copy todir=\"/tmp\">
<mapper type=\"glob\" from=\"*.php\"
to=\"*.php.bak\" />
<fileset dir=\"./app\"
includes=\"**/*.php\" />
</copy>
<copy todir=\"${deploy.dir}\">
<mapper type=\"regexp\"
from=\"^(.*)-(.*)\\.conf\\.xml\"
to=\"\\1.\\2.php\"/>
<fileset dir=\"${config.src.dir}\"
includes=\"**/*.conf.xml\" />
</copy>
Hans Lellelid: Putting Phing to Work for You 20

Data Transformation
• The <filterchain> type adds data
filtering/transforming capabilities to
supporting tasks.
• Tasks that support <filterchain> include
<copy>, <move>, <append> + more
• For example:
– Strip comments from files
– Replace values in files (+ regexp)
– Perform XSLT transformation
• Easily add your own.
Hans Lellelid: Putting Phing to Work for You 21

Filtering examples
<copy todir=\"${build}/htdocs\">
<fileset includes=\"*.html\"/>
<filterchain>
<replaceregexp>
<regexp pattern=\"\\r\\n\"
replace=\"\\n\"/>
</replaceregexp>
<tidyfilter encoding=\"utf8\">
<config name=\"indent\"
value=\"true\"/>
</tidyfilter>
</filterchain>
</copy>
Hans Lellelid: Putting Phing to Work for You 22

Other Tasks
Hans Lellelid: Putting Phing to Work for You 23

PDO Task
• <pdo> task allows you to execute SQL
statements from
– The buildfile itself
– One or more files
• Transactions can be explicitly demarcated.
• Output can be formatted with a provided or
custom formatter.
Hans Lellelid: Putting Phing to Work for You 24

User Input
• The <propertyprompt> task provides an
basic, easy way to set a value from user
input.
• The <input> task provides a more feature
rich version.
– Special handling of yes/no, multiple choice
– Support for input validation
Hans Lellelid: Putting Phing to Work for You 25

Build API Docs
• The <phpdoc> task provides a wrapper for
the PhpDocumentor application.
• A few advantages over standalone phpdoc:
– Use properties from build script
– Use Phing features like filesets
Hans Lellelid: Putting Phing to Work for You 26

Unit Testing
• Phing has extensive support for PHPUnit
and SimpleTest unit testing frameworks
• PHPUnit tasks provide support for
– Batch testing using <fileset> to select all
the tests you wish to run.
– Output in XML (Junit-compatible) and Plain
text.
– Report generator creates XHTML reports
using XSLT
– Code coverage reports (requires Xdebug)
Hans Lellelid: Putting Phing to Work for You 27

Continuous Integration
• Code -> Commit -> Build -> Test ->
Report
• CI tools watch the repository and provide
automated building, testing, reporting.
• CruiseControl is probably the most well-
known.
• Xinc provides CI tool functionality written in
PHP.
• Xinc is built to use Phing
• CruiseControl also supports Phing
Hans Lellelid: Putting Phing to Work for You 28

Extending Phing
Hans Lellelid: Putting Phing to Work for You 29

Paths for Extension
• Embedding PHP in build file.
• Write your own class to provide any of the
functionality we have seen:
– Task
– Type
– Selector
– Filter
– Mapper
– Listener (logger)
– Input Handler
Hans Lellelid: Putting Phing to Work for You 30

Embedding PHP
• The <php> task allows you to evaluate a
PHP expression, function call, etc. and store
result in a property.
• The <adhoc> task allows you to embed
PHP directly. Useful for including setup
files.
<adhoc><![CDATA[
require_once 'propel/Propel.php';
Propel::init('bookstore-conf.php');
]]></adhoc>
Hans Lellelid: Putting Phing to Work for You 31

Writing a Task
• Extend Task
• Add setter methods for any params your
task accepts.
• Implement public function main()
• Abstract subclasses exist to make life
easier (e.g. MatchingTask)
Hans Lellelid: Putting Phing to Work for You 32

Sample Task
class SampleTask extends Task {
private $var;
public function setVar($v) {
$this->var = $v;
}
public function main() {
$this->log(\"value: \".$this->var);
}
}
Hans Lellelid: Putting Phing to Work for You 33

More Complex Task
• Adding support for CDATA text.
• Adding support for Fileset, Filelist,
Filterchain child elements.
• Supporting nested arbitrary classes ...
Hans Lellelid: Putting Phing to Work for You 34

Data Types
• Classes that can be shared by different
tasks.
• Extend DataType
• Add setter methods for any params your
data type accepts/expects.
Hans Lellelid: Putting Phing to Work for You 35

Filters
• Extend BaseFilterReader or
BaseParamFilterReader and implement
ChainableReader.
• Implement read() and chain() methods.
– Read stream and return -1 when stream is
exhausted.
• If using params, you must initialize them
locally.
• Use <filterreader classname=”YourClass”>
in your build file.
Hans Lellelid: Putting Phing to Work for You 36

Selectors
• Extend BaseExtendSelector
• Implement isSelected()
• Use <custom> tag in your build file.
Hans Lellelid: Putting Phing to Work for You 37

Mappers
• Implement FileNameMapper
• Implement main(filename), setFrom(str),
setTo(str)
• Use <mapper classname=”...”> in your
build file.
Hans Lellelid: Putting Phing to Work for You 38

Build Listeners
• Implement BuildListener (or
BuildLogger which expects streams)
• Register on the commandline using
-listener (or -logger) option.
Hans Lellelid: Putting Phing to Work for You 39

Input Handlers
• Implement InputHandler interface
– Implement the handleInput(InputRequest)
method.
• Register on the commandline using
-listener (or -inputhandler) option.
Hans Lellelid: Putting Phing to Work for You 40

Where next?
• Visit http://phing.info for downloads,
documentation, and issue tracking.
• Ask questions on the mailing lists.
– users@phing.tigris.org
– dev@phing.tigris.org
Hans Lellelid: Putting Phing to Work for You 41