php-coveralls

PHP client library for Coveralls.

Prerequisites

• PHP 5.5+ for 2.x or 5.3+ for 1.x
• On GitHub
• Building on Travis CI, CircleCI, Jenkins or Codeship
• Testing by PHPUnit or other testing framework that can generate clover style coverage report

Installation

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:

https://github.com/php-coveralls/php-coveralls/releases/download/v2.2.0/php-coveralls.phar

Download the file and add exec permissions:

$ wget https://github.com/php-coveralls/php-coveralls/releases/download/v2.2.0/php-coveralls.phar
$ chmod +x php-coveralls.phar

Install by composer

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

$ composer require --dev php-coveralls/php-coveralls

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

$ composer require --dev php-coveralls/php-coveralls '^2.2'

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:

# HTTP
$ git clone https://github.com/php-coveralls/php-coveralls.git
# SSH
$ git clone git@github.com:php-coveralls/php-coveralls.git

Configuration

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

PHPUnit

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 ...>
    <logging>
        ...
        <log type="coverage-clover" target="build/logs/clover.xml"/>
        ...
    </logging>
</phpunit>

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

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

phpcov

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.

composer.json

    "require-dev": {
        "php-coveralls/php-coveralls": "^2.2",
        "phpunit/phpcov": "^2.0"
    },

phpunit configuration

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

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

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 ...

clover.xml

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"/>

GitHub Actions

Add a new step after phpunit generate coverage report.

- name: Upload coverage results to Coveralls
  env:
    COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: |
    composer global require twinh/php-coveralls
    php-coveralls --coverage_clover=build/logs/clover.xml -v

Parallel Job Example

name: Build

on: [push, pull_request]

env:
  extensions: mbstring, mysql
  key: cache-v1 # can be any string, change to clear the extension cache.

jobs:
  phpunit:
    runs-on: ${{ matrix.operating-system }}
    strategy:
      fail-fast: false
      matrix:
        operating-system: [ubuntu-latest]
        php-versions: ['7.2', '7.3', '7.4']
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Setup cache environment
        id: cache-env
        uses: shivammathur/cache-extensions@v1
        with:
          php-version: ${{ matrix.php-versions }}
          extensions: ${{ env.extensions }}
          key: ${{ env.key }}

      - name: Cache extensions
        uses: actions/cache@v1
        with:
          path: ${{ steps.cache-env.outputs.dir }}
          key: ${{ steps.cache-env.outputs.key }}
          restore-keys: ${{ steps.cache-env.outputs.key }}

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-versions }}
          extensions: ${{ env.extensions }}
          coverage: xdebug

      - name: Get composer cache directory
        id: composer-cache
        run: echo "::set-output name=dir::$(composer config cache-files-dir)"

      - name: Cache composer dependencies
        uses: actions/cache@v1
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          # Use composer.json for key, if composer.lock is not committed.
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
          restore-keys: ${{ runner.os }}-composer-

      - name: Install
        run: |
          composer install --no-progress --no-suggest --prefer-dist --optimize-autoloader

      - name: Run
        run: |
          vendor/bin/phpunit --verbose --stderr --coverage-clover build/logs/clover.xml --coverage-text

      - name: Upload coverage results to Coveralls
        env:
          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          COVERALLS_PARALLEL: true
          COVERALLS_FLAG_NAME: php-${{ matrix.php-versions }}
        run: |
          composer global require twinh/php-coveralls
          php-coveralls --coverage_clover=build/logs/clover.xml -v

  coveralls-finish:
    needs: [phpunit]
    runs-on: ubuntu-18.04
    steps:
      - name: Coveralls Finished
        uses: coverallsapp/github-action@master
        with:
          github-token: ${{ secrets.github_token }}
          parallel-finished: true

Travis CI

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

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

matrix:
  allow_failures:
    - php: 5.5

install:
  - curl -s http://getcomposer.org/installer | php
  - php composer.phar install --dev --no-interaction
script:
  - mkdir -p build/logs
  - php vendor/bin/phpunit -c phpunit.xml.dist

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

CircleCI

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.

machine:
  php:
    version: 5.4.10

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

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

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

Codeship

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 http://getcomposer.org/installer | 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/php-coveralls

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

In the "Configure your environment variables" section:

COVERALLS_REPO_TOKEN=your_token

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.

$ export COVERALLS_RUN_LOCALLY=1

# 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/php-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)
• --json_path (-o): Used to specify where to output json_file that will be uploaded to Coveralls API. (default: build/logs/coveralls-upload.json)
• --root_dir (-r): Root directory of the project. (default: ".")

.coveralls.yml

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 coveralls.io).

• 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.

• entry_point: Used to specify API endpoint for sending reports. Useful when using self-hosted coveralls or other other, similar service (eg opencov). Default is https://coveralls.io.
• 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.

#.coveralls.yml

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

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

# array
# specify files
coverage_clover:
  - 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

Wiki

See wiki