PHP client library for Coveralls API

Installs: 923 804

Dependents: 2 981

Stars: 242

Watchers: 22

Forks: 65

Open Issues: 10

v1.0.1 2016-01-20 17:35 UTC


Build Status Coverage Status Dependency Status

Latest Stable Version Total Downloads

PHP client library for Coveralls.



Download phar file

We started to create a phar file, starting from the version 0.7.0 release. It is available at the URLs like:

Download the file and add exec permissions:

$ wget
$ chmod +x coveralls.phar

Install by composer

To install php-coveralls with Composer, run the following command:

$ composer require satooshi/php-coveralls

If you need support for PHP versions older than 5.5, you will need to use a 1.x version:

$ composer require satooshi/php-coveralls '~1.0'

You can see this library on Packagist.

Composer installs autoloader at ./vendor/autoloader.php. If you use php-coveralls in your php script, add:

require_once 'vendor/autoload.php';

If you use Symfony2, autoloader has to be detected automatically.

Use it from your git clone

Or you can use git clone command:

$ git clone
$ git clone


Currently php-coveralls supports clover style coverage report and collects coverage information from clover.xml.


Make sure that phpunit.xml.dist is configured to generate "coverage-clover" type log named clover.xml like the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
        <log type="coverage-clover" target="build/logs/clover.xml"/>

You can also use --coverage-clover CLI option.

phpunit --coverage-clover build/logs/clover.xml


Above settings are good for most projects if your test suite is executed once a build and is not divided into several parts. But if your test suite is configured as parallel tasks or generates multiple coverage reports through a build, you can use either coverage_clover configuration in .coveralls.yml (see below coverage clover configuration section) to specify multiple clover.xml files or phpcov for processing coverage reports.

    "require-dev": {
        "satooshi/php-coveralls": "dev-master",
        "phpunit/phpcov": "2.*"
phpunit configuration

Make sure that phpunit.xml.dist is configured to generate "coverage-php" type log:

<?xml version="1.0" encoding="UTF-8"?>
<phpunit ...>
        <log type="coverage-php" target="build/cov/coverage.cov"/>

You can also use --coverage-php CLI option.

# use --coverage-php option instead of --coverage-clover
phpunit --coverage-php build/cov/coverage-${component_name}.cov
phpcov configuration

And then, execute phpcov.php to merge coverage.cov logs.

# get information
php vendor/bin/phpcov.php --help

# merge coverage.cov logs under build/cov
php vendor/bin/phpcov.php merge --clover build/logs/clover.xml build/cov

# in case of memory exhausting error
php -d memory_limit=-1 vendor/bin/phpcov.php ...


php-coveralls collects count attribute in a line tag from clover.xml if its type attribute equals to stmt. When type attribute equals to method, php-coveralls excludes its count attribute from coverage collection because abstract method in an abstract class is never counted though subclasses implement that method which is executed in test cases.

<!-- this one is counted as code coverage -->
<line num="37" type="stmt" count="1"/>
<!-- this one is not counted -->
<line num="43" type="method" name="getCommandName" crap="1" count="1"/>

Travis CI

Add php coveralls.phar or php vendor/bin/coveralls to your .travis.yml at after_success.

# .travis.yml
language: php
  - 5.5
  - 5.4
  - 5.3

    - php: 5.5

  - curl -s | php
  - php composer.phar install --dev --no-interaction
  - mkdir -p build/logs
  - php vendor/bin/phpunit -c phpunit.xml.dist

  - travis_retry php vendor/bin/coveralls
  # or enable logging
  - travis_retry php vendor/bin/coveralls -v


Enable Xdebug in your circle.yml at dependencies section since currently Xdebug extension is not pre-enabled. composer and phpunit are pre-installed but you can install them manually in this dependencies section. The following sample uses default ones.

    version: 5.4.10

## Customize dependencies
    - mkdir -p build/logs
    - composer install --dev --no-interaction
    - sed -i 's/^;//' ~/.phpenv/versions/$(phpenv global)/etc/conf.d/xdebug.ini

## Customize test commands
    - phpunit -c phpunit.xml.dist

Add COVERALLS_REPO_TOKEN environment variable with your coveralls repo token on Web UI (Tweaks -> Environment Variable).


You can configure CI process for Coveralls by adding the following commands to the textarea on Web UI (Project settings > Test tab).

In the "Modify your Setup Commands" section:

curl -s | php
php composer.phar install --dev --no-interaction
mkdir -p build/logs

In the "Modify your Test Commands" section:

php vendor/bin/phpunit -c phpunit.xml.dist
php vendor/bin/coveralls

Next, open Project settings > Environment tab, you can set COVERALLS_REPO_TOKEN environment variable.

In the "Configure your environment variables" section:


From local environment

If you would like to call Coveralls API from your local environment, you can set COVERALLS_RUN_LOCALLY environment variable. This configuration requires repo_token to specify which project on Coveralls your project maps to. This can be done by configuring .coveralls.yml or COVERALLS_REPO_TOKEN environment variable.


# either env var
$ export COVERALLS_REPO_TOKEN=your_token

# or .coveralls.yml configuration
$ vi .coveralls.yml
repo_token: your_token # should be kept secret!

php-coveralls set the following properties to json_file which is sent to Coveralls API (same behaviour as the Ruby library will do except for the service name).

  • service_name: php-coveralls
  • service_event_type: manual

CLI options

You can get help information for coveralls with the --help (-h) option.

php vendor/bin/coveralls --help
  • --config (-c): Used to specify the path to .coveralls.yml. Default is .coveralls.yml
  • --verbose (-v): Used to show logs.
  • --dry-run: Used not to send json_file to Coveralls Jobs API.
  • --exclude-no-stmt: Used to exclude source files that have no executable statements.
  • --env (-e): Runtime environment name: test, dev, prod (default: "prod")
  • --coverage_clover (-x): Coverage clover xml files(allowing multiple values)
  • --root_dir (-r): Root directory of the project. (default: ".")


php-coveralls can use optional .coveralls.yml file to configure options. This configuration file is usually at the root level of your repository, but you can specify other path by --config (or -c) CLI option. Following options are the same as Ruby library (see reference on

  • repo_token: Used to specify which project on Coveralls your project maps to. This is only needed for repos not using CI and should be kept secret
  • service_name: Allows you to specify where Coveralls should look to find additional information about your builds. This can be any string, but using travis-ci or travis-pro will allow Coveralls to fetch branch data, comment on pull requests, and more.

Following options can be used for php-coveralls.

  • coverage_clover: Used to specify the path to clover.xml. Default is build/logs/clover.xml
  • json_path: Used to specify where to output json_file that will be uploaded to Coveralls API. Default is build/logs/coveralls-upload.json.
# .coveralls.yml example configuration

# same as Ruby lib
repo_token: your_token # should be kept secret!
service_name: travis-pro # travis-ci or travis-pro

# for php-coveralls
coverage_clover: build/logs/clover.xml
json_path: build/logs/coveralls-upload.json

coverage clover configuration

You can specify multiple clover.xml logs at coverage_clover. This is useful for a project that has more than two test suites if all of the test results should be merged into one json_file.


# single file
coverage_clover: build/logs/clover.xml

# glob
coverage_clover: build/logs/clover-*.xml

# array
# specify files
  - build/logs/clover-Auth.xml
  - build/logs/clover-Db.xml
  - build/logs/clover-Validator.xml

You can also use --coverage_clover (or -x) command line option as follows:

coveralls --coverage_clover=build/logs/my-clover.xml

root_dir detection and override

This tool assume the current directory is the project root directory by default. You can override it with --root_dir command line option.

Change log

See changelog


See wiki