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.
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.
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.
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 | Required for | Source |
---|---|---|
PHP 5.2+ | Execution | http://www.php.net |
PHPUnit 3.6.0+ | Optional; enables additional task(s) | http://www.phpunit.de |
Xdebug 2.0.5+ | Optional; enables additional task(s) | http://www.xdebug.org |
SimpleTest 1.0.1 beta+ | Optional; enables additional task(s) | http://simpletest.sourceforge.net |
phpDocumentor 2.0.0b7+ (PEAR package) | Optional; enables additional task(s) | http://pear.phpdoc.org |
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 |
Phing does not work with safe mode enabled!
Phing is free software distributed under the terms of the LGPL.
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.
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.
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).
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.
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
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
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.
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.
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