Phing Guide - Setup

# 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
Creole 1.1.0+ | Optional; enables additional task(s) | http://creole.phpdb.org
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.11.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:

- 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).
- Set the PHP_CLASSPATH environment variable (see the section below). This should be set at least point to PHING_HOME/classes. Alternatively, you can also just add the phing/classes directory to your PHP include_path ini setting.
- 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

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:

- If you want Phing to be able to use other packages / classes, you can either add them to the PHP_CLASSPATH or 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.

## 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 [targetname]

at the command line (where [targetname] is the target you want to be executed). 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 propery ftp.upload set to true.

    $ phing -Dftp.upload=true