Setting-Up Phing

The goal of this chapter is to help you obtain and correctly setup and execute Phing on your operating system. Once you setup Phing properly you shouldn't need to revisit this chapter, unless you're re-installing or moving your installation to another platform.

System Requirements

To use Phing you must have installed PHP version 5.2 or above compiled --with-libxml2, as well as --with-xsl if you want to make use of advanced functionality.

For more information on PHP and the required modules see the PHP [php] website. For a brief list of software dependencies see below.

Operating Systems

Designed for portability from the get go, Phing runs on all platforms that run PHP. However some advanced functionality may not work properly or is simply ignored on some platforms (i.e. chmod on the Windows platform).

To get the most out of Phing, a Unix style platform is recommended. Namely: Linux, FreeBSD, OpenBSD, etc.

Software Dependencies

For a detailed list of required / optional sofware and libraries, refer to the following table of Software Dependencies.

NB: This list is not exhaustive, please refer to individual Phing tasks to find out additional software requirements.

Software Dependencies
Software Required for Source
PHP 5.2+ Execution http://www.php.net
PHPUnit 3.4.0+ Optional; enables additional task(s) http://www.phpunit.de
Xdebug 2.0.0+ Optional; enables additional task(s) http://www.xdebug.org
SimpleTest 1.0.1 beta+ Optional; enables additional task(s) http://simpletest.sourceforge.net
PhpDocumentor 1.4.0+ (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/PhpDocumentor
VersionControl_SVN (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/VersionControl_SVN
VersionControl_Git (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/VersionControl_Git
PHP_CodeSniffer (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/PHP_CodeSniffer
Archive_Tar (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/Archive_Tar
Services_Amazon_S3 (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/Services_Amazon_S3
HTTP_Request2 (PEAR package) Optional; enables additional task(s) http://pear.php.net/package/HTTP_Request2
PHP Depend Optional; enables additional task(s) http://www.pdepend.org
PHP Mess Detector Optional; enables additional task(s) http://www.phpmd.org
PHP Copy/Paste Detector Optional; enables additional task(s) http://pear.phpunit.de
DocBlox 0.17.0+ Optional; enables additional task(s) http://www.docblox-project.org

Phing does not work with safe mode enabled!

Obtaining Phing

Phing is free software distributed under the terms of the LGPL.

Distribution Files

There are several ways to get a Phing distribution package. If you do not want to participate in developing Phing itself it is recommended that you get the latest snapshot or stable packaged distribution. If you are interested in helping with Phing development, get a CVS revision of the files, as described below.

The easiest way to obtain the distribution package is to visit the Phing website [phing] and download the current distribution package in the format you desire.

As of version 2.0, you have the option of downloading a PEAR-installable package or the full phing distribution. If you wish to modify phing we suggestion downloading the full version so that you can (e.g.) create your own PEAR package. If you simply wish to use Phing for your own project or need it to build another package, download & install the PEAR package.

Getting A Development Copy From Subversion

You are encouraged to contibute to the development of Phing. If you want to participate or if you are simply interested in the latest features and development, obtain a Subversion copy as described in the following paragraphs.

The SVN revisions of Phing are not bullet-proof and may fail to execute properly on your machine. Only obtain the development versions if you are absolutely aware of limitations and constraints of such an action. Additionally you should sign up to the development mailinglist to report and notice errors and incompatibilities.

We assume that you are running a Unix style operating system. So we expect the Subversion software is installed ant the svn executable is in your system's search path. However, the steps for a Windows based system are very similar. There is plenty additional information available on how to use Subversion [svn-howto].

To check out the project source repository type:

$> svn checkout http://svn.phing.info/trunk

You can also browse the entire Phing source (including previous versions and development branches) on http://www.phing.info/trac/browser.

PEAR Install

The easiest way to install Phing is using the PEAR installer. Provided that the package you downloaded is a the PEAR-ready package, you can install Phing simply from the command line (Unix or Windows):

$> pear channel-discover pear.phing.info
$> 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).

Non-PEAR Install

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 .

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:

If you are using Phing in conjunction with another application, you may need to add additional paths to PHP_CLASSPATH.

Unix

Assuming you are running a Unix dialect operating system with the bash bourne shell and Phing is installed in /opt/phing . The following sets up the environment properly:

  export PHP_COMMAND=/usr/bin/php
  export PHING_HOME=/opt/phing
  export PHP_CLASSPATH=${PHING_HOME}/classes
  export PATH=${PATH}:${PHING_HOME}/bin

Windows

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

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

Advanced

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

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

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.

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 other 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 propery ftp.upload set to true.

$ phing -Dftp.upload=true