> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shivammathur/setup-php/llms.txt
> Use this file to discover all available pages before exploring further.

# Code Coverage

> Configure code coverage drivers in your GitHub Actions workflow using Xdebug, PCOV, or disable coverage entirely for better performance.

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.

```yaml theme={null}
- 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`:

```yaml theme={null}
- name: Setup PHP with Xdebug 2.x
  uses: shivammathur/setup-php@v2
  with:
    php-version: '7.4'
    coverage: xdebug2
```

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

## PCOV

Specify `coverage: pcov` to enable PCOV and disable Xdebug. PCOV requires PHP 7.1 or newer.

```yaml theme={null}
- 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`:

```yaml theme={null}
- 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:

```yaml theme={null}
- name: Setup PCOV clobber for older PHPUnit
  run: |
    composer require pcov/clobber
    vendor/bin/pcov clobber
```

## Xdebug vs PCOV comparison

<Tabs>
  <Tab title="Xdebug">
    ```yaml theme={null}
    - 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+.
  </Tab>

  <Tab title="PCOV">
    ```yaml theme={null}
    - name: Setup PHP with PCOV
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: pcov

    - name: Run tests with coverage
      run: vendor/bin/phpunit --coverage-clover coverage.xml
    ```

    PCOV is a lightweight coverage-only driver with lower overhead than Xdebug. Requires PHP 7.1+ and PHPUnit 8+.
  </Tab>
</Tabs>

## Disabling coverage

Specify `coverage: none` to disable both Xdebug and PCOV:

```yaml theme={null}
- 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:

<AccordionGroup>
  <Accordion title="Not generating coverage reports">
    If your workflow runs tests without producing a coverage report, disable coverage to avoid the overhead of the driver being loaded on every request.
  </Accordion>

  <Accordion title="Using phpdbg">
    When running tests through `phpdbg`, coverage drivers are not needed and may cause conflicts.
  </Accordion>

  <Accordion title="Profiling with Blackfire">
    Xdebug and PCOV conflict with Blackfire profiling. Always disable coverage when using Blackfire:

    ```yaml theme={null}
    - name: Setup PHP for Blackfire profiling
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.5'
        coverage: none
        tools: blackfire
    ```
  </Accordion>

  <Accordion title="Using PHP in JIT mode">
    JIT conflicts with Xdebug, PCOV, and any extension that overrides `zend_execute_ex`. You must set `coverage: none` when enabling JIT:

    ```yaml theme={null}
    - 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
    ```
  </Accordion>
</AccordionGroup>

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

```yaml theme={null}
- name: Setup PHP (no coverage overhead)
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    coverage: none
```