Chapter 3. Installing PHPUnit

There a three supported ways of installing PHPUnit. You can use the PEAR Installer or Composer to download and install PHPUnit as well as its dependencies. You can also download a PHP Archive (PHAR) of PHPUnit that has all required (as well as some optional) dependencies of PHPUnit bundled in a single file.

Note

Support for Composer and PHP Archive (PHAR) was added in PHPUnit 3.7 (and is known to be stable since PHPUnit 3.7.5). Earlier releases of PHPUnit are not available through these distribution channels.

Note

PHPUnit 3.7 requires PHP 5.3.3 (or later) but PHP 5.4.7 (or later) is highly recommended.

PHP_CodeCoverage, the library that is used by PHPUnit to collect and process code coverage information, depends on Xdebug 2.0.5 (or later) but Xdebug 2.2.0 (or later) is highly recommended.

PEAR

The following two commands (which you may have to run as root) are all that is required to install PHPUnit using the PEAR Installer:

pear config-set auto_discover 1
pear install pear.phpunit.de/PHPUnit

Caution

Depending on your OS distribution and/or your PHP environment, you may need to install PEAR or update your existing PEAR installation before you can proceed with the instructions in this section.

sudo pear upgrade PEAR usually suffices to upgrade an existing PEAR installation. The PEAR Manual explains how to perform a fresh installation of PEAR.

Composer

To add PHPUnit as a local, per-project dependency to your project, simply add a dependency on phpunit/phpunit to your project's composer.json file. Here is a minimal example of a composer.json file that just defines a development-time dependency on PHPUnit 3.7:

{
    "require-dev": {
        "phpunit/phpunit": "3.7.*"
    }
}

For a standalone, system-wide installation via Composer, a composer.json similar to the one shown below can be used from an arbitary directory.

{
    "require": {
        "phpunit/phpunit": "3.7.*"
    },
    "config": {
        "bin-dir": "/usr/local/bin/"
    }
}

PHP Archive (PHAR)

You can also download a PHP Archive (PHAR) of PHPUnit that has all required (as well as some optional) dependencies of PHPUnit bundled in a single file:

wget http://pear.phpunit.de/get/phpunit.phar
chmod +x phpunit.phar

Optional packages

The following optional packages are available:

DbUnit

DbUnit port for PHP/PHPUnit to support database interaction testing.

This package can be installed via PEAR using the following command:

pear install phpunit/DbUnit

This package can be installed via Composer by addding the following "require-dev" dependency:

"phpunit/dbunit": ">=1.2"

PHP_Invoker

A utility class for invoking callables with a timeout. This package is required to enforce test timeouts in strict mode.

This package can be installed using the following command:

pear install phpunit/PHP_Invoker

This package can be installed via Composer by addding the following "require-dev" dependency:

"phpunit/php-invoker": "*"

PHPUnit_Selenium

Selenium RC integration for PHPUnit.

This package can be installed via PEAR using the following command:

pear install phpunit/PHPUnit_Selenium

This package can be installed via Composer by addding the following "require-dev" dependency:

"phpunit/phpunit-selenium": ">=1.2"

PHPUnit_Story

Story-based test runner for Behavior-Driven Development with PHPUnit.

This package can be installed via PEAR using the following command:

pear install phpunit/PHPUnit_Story

This package can be installed via Composer by addding the following "require-dev" dependency:

"phpunit/phpunit-story": "*"

PHPUnit_SkeletonGenerator

Tool that can generate skeleton test classes from production code classes and vice versa.

This package can be installed using the following command:

pear install phpunit/PHPUnit_SkeletonGenerator

PHPUnit_TestListener_DBUS

A TestListener that sends events to DBUS.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TestListener_DBUS

PHPUnit_TestListener_XHProf

A TestListener that uses XHProf for automated profiling of the tested code.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TestListener_XHProf

PHPUnit_TicketListener_Fogbugz

A ticket listener that interacts with the Fogbugz issue API.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TicketListener_Fogbugz

PHPUnit_TicketListener_GitHub

A ticket listener that interacts with the GitHub issue API.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TicketListener_GitHub

PHPUnit_TicketListener_GoogleCode

A ticket listener that interacts with the Google Code issue API.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TicketListener_GoogleCode

PHPUnit_TicketListener_Trac

A ticket listener that interacts with the Trac issue API.

This package can be installed using the following command:

pear install phpunit/PHPUnit_TicketListener_Trac

Upgrading

This section serves as a collection of minor BC issues that one might run into when upgrading from PHPUnit 3.6 to PHPUnit 3.7.

The upgrade should be rather easy and work without any issues as it was tested against all major Open Source frameworks and there was not a single problem for them. Still every project is different and if you did not get around to trying one of the release candidates and have ran into an issue this document might provide some help.

Removed deprecated OutputTestCase

The class PHPUnit_Extensions_OutputTestCase has been removed. PHPUnit 3.6 issued a deprecation notice when it was used. To see how output can now be tested look into the section called “Testing Output”.

Current working directory will be restored after each test case

If a test changes the current working directory (cwd) PHPUnit ran into issues when generating code coverage output. Now that the cwd is restored after each test case you might find that one of your tests depended on another test changing the cwd. Something that isn't desirable anyways and should be easy to fix.

Test listeners trigger one autoload call

When using custom test listeners as described in the section called “Test Listeners” PHPUnit silently ignored missing test listeners and it was quite hard to debug that issues for the user. Now one autoload call will be triggered trying to locate the class. If your autoloader produces an error when it doesn't find a test listener you might run into an issue here. Removing the listener or making sure it's loaded in your bootstrap.php will solve this.

Parameters for mock objects do not get cloned anymore

Previously all object parameters where cloned when mocking. This lead to issues when testing trying to check whether the same object was passed to method or not and other problem with uncloneable objects. As a long standing feature request by many this behavior was changed. Example 10.14 shows where the new implementation could be useful. Example 10.15 shows how to switch back to previous behavior.

addUncoveredFilesFromWhitelist was removed in favor of processUncoveredFilesFromWhitelist

When generating code coverage and using <whitelist addUncoveredFilesFromWhitelist="true"> all uncovered files got included by PHPUnit. This was an issue for people with executable code in those files. PHPUnit will now scan the file and guess what code is executable and what code is not without including it. This might lead to different code coverage reports.

To switch back to the old behavior the setting <whitelist processUncoveredFilesFromWhitelist=="true"> can be used. If you want the behavior with PHPUnit 3.6. and 3.7. it is possible to use both settings for a while.

Default value of cacheTokens changed to false

Since PHPUnit 3.7.2 we turned off the caching of tokenized files by default. When processing code coverage reports for big projects this cache consumed a lot of memory and due to the change in whitelist behavior it was problematic for folks with code bases with more than a couple of thousand classes.

If your project is smaller or you have enough memory you will get a runtime benefit by adding cacheTokens="true" to your phpunit.xml file. See the section called “PHPUnit”.