Phing: Building in PHP
Hans Lellelid
International PHP Conference
2007-11-06

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: Phing: Building in PHP 2

This Talk
• Brief Overview & “Justification”
• Basic Usage
• Packaginig & Deployment
• Development Cycle
• Extending Phing
• Slides available at
http://phing.info/presentations/
Hans Lellelid: Phing: Building in PHP 3

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)
• It seems to have caught on.
– Propel, Prado, Symfony, Agavi, Xinc (to
name a few)
Hans Lellelid: Phing: Building in PHP 4

Why do I need a build tool
for PHP?
Hans Lellelid: Phing: Building in PHP 5

Building != Compiling
• In this context, “building” is really any non-
development task that supports your
application.
• This could include
– Configuring
– Packaging
– Uploading
– Testing
– Etc.
Hans Lellelid: Phing: Building in PHP 6

PHP apps > web pages
• PHP is no longer a simple web scripting
language.
• We are using PHP to do all sorts of things
on the CLI:
– Run unit tests (PHPUnit, SimpleTest)
– Build API docs (PhpDocumentor)
– Install and Package (PEAR)
Hans Lellelid: Phing: Building in PHP 7

Web apps get deployed
• PHP web applications do eventually get
deployed.
• Deployment has a whole lot of implications:
– Permissions
– Environment setup
– App Configuration
Hans Lellelid: Phing: Building in PHP 8

Phing can help.
• Anything you can do with a shell script you
can do with Phing.
• And a whole lot more ...
– Transform directories and files.
– Configure your application
– Prepare files for deployment
– Run unit tests
– Do other useful stuff – like SVN commits or
db initialization.
Hans Lellelid: Phing: Building in PHP 9

But why Phing specifically?
• Other choices do exist: Ant, Rake, NAnt
• With Phing you only need PHP.
• A PHP tool for PHP apps just makes a lot of
sense:
– Familiar territory, common environment
– You can embed PHP directly in your build
scripts.
– You can integrate your own application code
into Phing extensions.
– Cross-pltform and small footprint.
Hans Lellelid: Phing: Building in PHP 10

How do I start using it?
Hans Lellelid: Phing: Building in PHP 11

The Basics
• Phing provides a simple shell script
(“phing”) that launches the Phing PHP app.
• You create build files in XML
• Build file organization:
– Tasks: a “build-in” piece of code that
performs a specific function. E.g. <mkdir>
– 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: Phing: Building in PHP 12

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: Phing: Building in PHP 13

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
– Anwers question “How to represent both
directory and class name in a single string?”
Hans Lellelid: Phing: Building in PHP 14

Packaging and Deployment
Hans Lellelid: Phing: Building in PHP 15

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: Phing: Building in PHP 16

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: Phing: Building in PHP 17

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: Phing: Building in PHP 18

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: Phing: Building in PHP 19

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: Phing: Building in PHP 20

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: Phing: Building in PHP 21

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: Phing: Building in PHP 22

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: Phing: Building in PHP 23

Packaging Tools
• The <tar> and <zip> tasks allow you to
bundle up your moved directories. (Of
course, they support <fileset> too.)
• <pearpkg> (and <pearpkg2>) tasks
allow you to create PEAR packages using
Phing.
Hans Lellelid: Phing: Building in PHP 24

Deployment Tools
• Deployment means different things for
different people.
• Phing includes some tasks to “put” stuff
places:
– <svn*> suite of tasks
– <scp>
• Database statement execution provided by
<pdo> and <creole> tasks.
Hans Lellelid: Phing: Building in PHP 25

Development Cycle
Hans Lellelid: Phing: Building in PHP 26

Building for Developers
• Not all build tasks are for deployment.
• Some build activities are specifically for
developer consumption:
– Checking validity or cleaning documents
– Building API documentation
– Running unit tests
• A more “traditional” build will likely also
play a part in developer build functionality.
Hans Lellelid: Phing: Building in PHP 27

Validating
• Phing includes several contributed lint tasks
for checking the validity of source code:
– <jslint> uses external jsl utility.
– <xmllint> uses built-in DOM support and
validates with a schema file.
– <phplint> users “php -l”
• The <tidy> task also provides ability to
perform validation and cleanup on HTML
documents.
Hans Lellelid: Phing: Building in PHP 28

PHP API Docs
• Phing includes support for
PhpDocumentor using the <phpdoc>
task.
<phpdoc title=\"API Documentation\"
destdir=\"apidocs\" sourcecode=\"no\"
output=\"HTML:Smarty:PHP\">
<fileset dir=\"./classes\">
<include name=\"**/*.php\" />
</fileset>
</phpdoc>
Hans Lellelid: Phing: Building in PHP 29

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: Phing: Building in PHP 30

PHPUnit Example
<phpunit2 haltonerror=\"true\"
haltonfailure=\"false\"
printsummary=\"true\">
<batchtest>
<fileset dir=\"${tests.dir}\">
<include name=\"**/*Test.php\"/>
</fileset>
</batchtest>
</phpunit2>
Hans Lellelid: Phing: Building in PHP 31

Continuous Integration
• Code -> Commit -> Build -> Test ->
Report
• CI tools watch the repository and provide
automated building, testing, reporting.
• CruiseControl has a Phing builder.
• Xinc provides CI tool functionality written in
PHP.
• Xinc is built to use Phing
Hans Lellelid: Phing: Building in PHP 32

Xinc Config Example
<projects>
<project name=\"Project Name\" interval=\"10\">
<modificationsets>
<svn directory=\"/var/projects/test\"/>
</modificationsets>
<builder type=\"phing\"
buildfile=\"/var/projects/test/build.xml\"
target=\"build\"/>
<publishers>
<email to=\"myemail@example.com\"
publishonfailure=\"true\"/>
</publishers>
</project>
</projects>
Hans Lellelid: Phing: Building in PHP 33

Extending Phing
Hans Lellelid: Phing: Building in PHP 34

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)
– ... and more.
Hans Lellelid: Phing: Building in PHP 35

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: Phing: Building in PHP 36

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: Phing: Building in PHP 37

Phing IRL
• Phing is being used by many organizations
and open-source projects.
• In the real world, Phing is used ...
– as an interactive CLI application
configuration or installation script,
– to upgrade production webservers,
– to manage product release builds,
– as a quick way to reorganize a directory
tree,
– & much, much more.
Hans Lellelid: Phing: Building in PHP 38

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: Phing: Building in PHP 39