Building a PHP project

What This Guide Covers

This guide covers build environment and configuration topics specific to PHP projects. Please make sure to read our Getting Started and general build configuration guides first.

PHP builds are not available on the OSX environment.

Choosing PHP versions to test against

PHP VM images on provide several PHP versions including XDebug as well as PHPUnit. Travis CI uses phpenv to manage the different PHP versions installed on the VM.

A minimalistic .travis.yml file would look like this:

language: php
  - '5.4'
  - '5.5'
  - '5.6'
  - '7.0'
  - '7.1'
  - hhvm
  - nightly

The previous example uses phpunit, the default build script, to build against the following list of PHP versions:

  • 5.4.x
  • 5.5.x
  • 5.6.x
  • 7.0.x
  • 7.1.x
  • hhvm
  • nightly

which are specified using aliases for the “most recent x.y.z release” provided on Travis CI of any given line. For a full listing of the supported versions see About Travis CI Environment.

You can see an example of version number aliases on github. For precise versions used in your build, consult “Build system information” in the build log.

Specifying exact versions like 5.3.8 is discouraged as it may break your build when we update PHP versions on Travis CI. PHP version 5.5.9 is supported, however, because it’s the version of PHP that is shipped with Ubuntu 14.04 LTS.

HHVM versions

Travis CI can test your PHP applications with HHVM.

Without specifying further, the latest version of HHVM available for the Ubuntu release your job is running on is used.

In addition, depending on the Ubuntu release, you can test with more HHVM versions.

HHVM versions on Precise

language: php
  - hhvm-3.3
  - hhvm-3.6

HHVM versions on Trusty

language: php
sudo: required
dist: trusty
group: edge
  - hhvm-3.3
  - hhvm-3.6
  - hhvm-3.9
  - hhvm-3.12
  - hhvm-3.15
  - hhvm-3.18
  - hhvm-nightly

Default Test Script (PHPUnit)

The default test script is PHPUnit. It comes packaged with PHP, but you can also install a specific version in a custom location. If you do install it separately, make sure you invoke the correct version by using the full path.

Travis CI looks for phpunit in the same order as Composer does and uses the first one found.

  1. $COMPOSER_BIN_DIR/phpunit
  2. phpunit found in the directory specified by bin-dir in composer.json
  3. vendor/bin/phpunit
  4. phpunit, which is found on $PATH (typically one that is pre-packaged with the PHP runtime)

If your project uses something other than PHPUnit, you can override the default test command.

Working with atoum

Instead of PHPunit, you can also use atoum to test your projects. For example:

before_script: composer require atoum/atoum
script: vendor/bin/atoum

Dependency Management (a.k.a. vendoring)

Before Travis CI can run your test suite, it may be necessary to pull down your project dependencies. It can be done using a PHP script, a shell script or anything you need. Define one or more commands you want Travis CI to use with the install option in your .travis.yml, for example:

install: php vendor/vendors.php

or, if you need to run multiple commands sequentially:

  - ./bin/ci/
  - php vendor/vendors.php

Even though installed dependencies will be wiped out between builds (VMs we run tests in are snapshotted), please be reasonable about the amount of time and network bandwidth it takes to install them.

Testing Against Multiple Versions of Dependencies (e.g. Symfony)

If you need to test against multiple versions of, say, Symfony, you can instruct Travis CI to do multiple runs with different sets or values of environment variables. Use env key in your .travis.yml file, for example:

  - SYMFONY_VERSION="2.0.*" DB=mysql
  - SYMFONY_VERSION="dev-master" DB=mysql

and then use ENV variable values in any later script like your dependencies installation scripts, test cases or test script parameter values.

Here is an example using the above ENV variable to modify the dependencies when using the composer package manager to run the tests against the 2 different versions of Symfony as defined above.

   - composer require symfony/framework-bundle:${SYMFONY_VERSION}

Here we use DB variable value to pick phpunit configuration file:

    script: phpunit --configuration $DB.phpunit.xml

The same technique is often used to test projects against multiple databases and so on.

To see real world examples, see:

Installing PEAR packages

If your dependencies include PEAR packages, the Travis CI PHP environment has the Pyrus and pear commands available:

pyrus install
pear install pear/PHP_CodeSniffer

After install you should refresh your path

phpenv rehash

For example, if you want to use phpcs, you should execute:

pyrus install pear/PHP_CodeSniffer
phpenv rehash

Then you can use phpcs like the phpunit command

Installing Composer packages

Note that we update composer every time we update the PHP build environment, which is every 30-60 days. Because composer has a time-based update warning, you may see messages such as this, which may be safely ignored:

Warning: This development build of composer is over 30 days old. It is recommended to update it by running "/home/travis/.phpenv/versions/5.6/bin/composer self-update" to get the latest version.

You can also install Composer packages into the Travis CI PHP environment. The composer command comes pre-installed, use the following:

composer install

To ensure that everything works, use http(s) URLs on Packagist and not git URLs.

PHP installation

You’ll find the default configure options used to build the different PHP versions used on Travis CI here, it will give you an overview of Travis CI’s PHP installation.

Please note the following differences among the different PHP versions available on Travis CI:

  • The OpenSSL extension is switched off on php 5.3.3 because of compilation problems with OpenSSL 1.0.
  • Different SAPIs:

    • 5.3.3 comes with php-cgi only.
    • 5.3.x (5.3.29) comes with php-fpm only (see this issue).
    • 5.4.x, 5.5.x, and 5.6.x come with php-cgi and php-fpm.

Custom PHP configuration

The easiest way to customize your PHP configuration is to use phpenv config-add to add a custom config file with your configuration directives:

before_script: phpenv config-add myconfig.ini

Make sure that your config file does not start with a dot (.) or a hyphen (-) as this will prevent PHP loading your custom settings.

And myconfig.ini:

extension = ""
date.timezone = "Europe/Paris"
default_socket_timeout = 120
# some other configuration directives...

You can also use this one line command in your .travis.yml:

before_script: echo 'date.timezone = "Europe/Paris"' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini

PHP extensions

Core extensions

See the default configure options to get an overview of the core extensions enabled.

Preinstalled PHP extensions

PHP 7.0

The following extensions are preinstalled for PHP 7.0 and nightly builds:

Please note that these extensions are not enabled by default with the exception of xdebug.

PHP 5.6 and below

For PHP versions up to 5.6, the following extensions are available:

Please note that these extensions are not enabled by default with the exception of xdebug.

Enabling preinstalled PHP extensions

You need to enable them by adding an extension="<extension>.so" line to a PHP configuration file (for the current PHP version). The easiest way to do this is by using phpenv to add a custom config file which enables and eventually configure the extension:

before_install: phpenv config-add myconfig.ini

Make sure that your config file does not start with a dot (.) or a hyphen (-) as this will prevent PHP loading your custom settings.

And myconfig.ini:

# some other mongo specific configuration directives
# or general custom PHP settings...

You can also use this one line command:

before_install: echo "extension = <extension>.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini

Disabling preinstalled PHP extensions

To disable xdebug, add this to your configuration:

  - phpenv config-rm xdebug.ini

Installing additional PHP extensions

It is possible to install custom PHP extensions into the Travis CI environment using PECL, but they have to be built against the PHP version being tested. Here is for example how the memcache extension can be installed:

pecl install <extension>

PECL will automatically enable the extension at the end of the installation. If you want to configure your extension, use the phpenv config-add command to add a custom ini configuration file in your before_script.

It is also possible to do the installation “manually”, but you’ll have to manually enable the extension after the installation either with phpenv config-add and a custom ini file or with this one line command:

echo "extension=<extension>.so" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini

See also the full script using midgard2.

If you need specific version of preinstalled extension, you need to force install specific version with the -f flag. For example:

pecl install -f mongo-1.2.12

Note on pecl install

Note that pecl install can fail if the requested version of the package is already installed.

Chef Cookbooks for PHP

If you want to learn all the details of how we build and provision multiple PHP installations, see our php, phpenv and php-build Chef cookbooks.

Apache + PHP

Currently Travis CI does not support mod_php for apache, but you can configure php-fpm for your integration tests.

In your .travis.yml:

  - sudo apt-get update
  - sudo apt-get install apache2 libapache2-mod-fastcgi
  # enable php-fpm
  - sudo cp ~/.phpenv/versions/$(phpenv version-name)/etc/php-fpm.conf.default ~/.phpenv/versions/$(phpenv version-name)/etc/php-fpm.conf
  - sudo a2enmod rewrite actions fastcgi alias
  - echo "cgi.fix_pathinfo = 1" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini
  - ~/.phpenv/versions/$(phpenv version-name)/sbin/php-fpm
  # configure apache virtual hosts
  - sudo cp -f build/travis-ci-apache /etc/apache2/sites-available/default
  - sudo sed -e "s?%TRAVIS_BUILD_DIR%?$(pwd)?g" --in-place /etc/apache2/sites-available/default
  - sudo service apache2 restart

Note that sudo is not available for builds that are running on container-based workers.

You will need to have build/travis-ci-apache file that will configure your virtual host as usual, the important part for php-fpm is this:

<VirtualHost *:80>
  # [...]

  DocumentRoot %TRAVIS_BUILD_DIR%

  <Directory "%TRAVIS_BUILD_DIR%">
    Options FollowSymLinks MultiViews ExecCGI
    AllowOverride All
    Order deny,allow
    Allow from all

  # Wire up Apache to use Travis CI's php-fpm.
  <IfModule mod_fastcgi.c>
    AddHandler php5-fcgi .php
    Action php5-fcgi /php5-fcgi
    Alias /php5-fcgi /usr/lib/cgi-bin/php5-fcgi
    FastCgiExternalServer /usr/lib/cgi-bin/php5-fcgi -host -pass-header Authorization

  # [...]

PHP nightly builds

Travis CI offers ability to test your PHP applications with a recent build of PHP.

You can specify this with:

language: php

  - nightly

This installation includes PHPUnit and Composer, and also has some extensions.

Build Matrix

For PHP projects, env and php can be given as arrays to construct a build matrix.