Skip to main content
The coverage input selects the code coverage driver. setup-php supports xdebug, pcov, and none. Only one driver can be active at a time.

​
Xdebug

Specify coverage: xdebug to enable Xdebug and disable PCOV. Xdebug runs on all PHP versions supported by setup-php. 
- name: Setup PHP with Xdebug
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: xdebug
When coverage: xdebug is set, the latest Xdebug version compatible with the specified PHP version is installed automatically.

​
Xdebug 2.x for PHP 7.x

If you need Xdebug 2.x on PHP 7.2, 7.3, or 7.4, use coverage: xdebug2: 
- name: Setup PHP with Xdebug 2.x
  uses: shivammathur/setup-php@v2
  with:
    php-version: '7.4'
    coverage: xdebug2
Xdebug is enabled by default on Ubuntu GitHub Actions images. If you are not generating coverage reports, disable it using coverage: none to improve PHP performance.

​
PCOV

Specify coverage: pcov to enable PCOV and disable Xdebug. PCOV requires PHP 7.1 or newer. 
- name: Setup PHP with PCOV
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: pcov

​
Custom source directory

By default, PCOV tracks coverage in src, lib, and app directories. If your source code is in a different directory, set pcov.directory via ini-values: 
- name: Setup PHP with PCOV (custom directory)
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    ini-values: pcov.directory=api
    coverage: pcov

​
PHPUnit compatibility

PHPUnit 8.x and above support PCOV out of the box. If you are using PHPUnit 5.x, 6.x, or 7.x, install the pcov/clobber package before running your tests: 
- name: Setup PCOV clobber for older PHPUnit
  run: |
    composer require pcov/clobber
    vendor/bin/pcov clobber

​
Xdebug vs PCOV comparison

- name: Setup PHP with Xdebug
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: xdebug

- name: Run tests with coverage
  run: vendor/bin/phpunit --coverage-clover coverage.xml
Xdebug provides coverage, debugging, and profiling. It works on all supported PHP versions and requires no additional setup for PHPUnit 5+.

​
Disabling coverage

Specify coverage: none to disable both Xdebug and PCOV: 
- name: Setup PHP without coverage
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none

​
When to disable coverage

Disable coverage in the following situations:
If your workflow runs tests without producing a coverage report, disable coverage to avoid the overhead of the driver being loaded on every request.
When running tests through phpdbg, coverage drivers are not needed and may cause conflicts.
Xdebug and PCOV conflict with Blackfire profiling. Always disable coverage when using Blackfire:
- name: Setup PHP for Blackfire profiling
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none
    tools: blackfire
JIT conflicts with Xdebug, PCOV, and any extension that overrides zend_execute_ex. You must set coverage: none when enabling JIT:
- name: Setup PHP with JIT
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none
    ini-values: opcache.enable_cli=1, opcache.jit=tracing, opcache.jit_buffer_size=64M

​
Performance note

Xdebug is enabled by default on Ubuntu GitHub Actions images. Even when you do not specify coverage: xdebug, the extension is already loaded and incurs a performance cost. For workflows that do not need coverage, explicitly set coverage: none to unload Xdebug and improve PHP execution speed. 
- name: Setup PHP (no coverage overhead)
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none

Build docs developers (and LLMs) love

Get started for freeTalk to us