PHP test coverage

SonarQube Cloud supports the reporting of test coverage information as part of the analysis of your PHP project. 

However, SonarQube Cloud does not produce the coverage report itself. Instead, you must set up a third-party tool to produce the report as part of your build process. You then need to configure your analysis to tell the SonarScanner where the report is located so that it can pick it up and send it to SonarQube Cloud, where it will be displayed on your project dashboard along with the other analysis metrics.

For PHP projects, we recommend PHPUnit for testing and coverage reporting.

Use CI-based, not automatic analysis

Usually, when you import a new PHP project, automatic analysis starts immediately. But, since coverage is not yet supported under automatic analysis, you will need to use CI-based analysis instead. This requires disabling automatic analysis. Here are the steps you need to follow:

If you have not yet imported your PHP project, just add an empty file called sonar-project.properties to the root of your repository, and then perform the import. SonarQube Cloud will assume that you want to set up a CI-based analysis and display the onboarding tutorial.

If you have already imported your project, then SonarQube Cloud has already run at least once using automatic analysis. Don’t worry, you can still convert your project to use a CI-based approach. Simply go to Administration > Analysis Method and switch SonarQube Cloud Automatic Analysis to OFF. Then, on the same screen, under Supported analysis methods find your preferred CI and select Follow the tutorial.

Follow the tutorial

At this point, you should be in the onboarding tutorial specific to your CI. Follow the tutorial and when it asks, What option best describes your build?, choose Other (for JS, TS, Go, Python, PHP, ...). When you are done with the tutorial, you should have a functioning CI-based analysis setup for your PHP  project. The next step is to adjust it to get coverage working.

Adjust your setup

To enable coverage you need to:

• Adjust your build process so that the coverage tool runs before the scanner report generation step runs.
• Make sure that the coverage tool writes its report file to a defined path in the build environment.
• Configure the scanning step of your build so that the scanner picks up the report file from that defined path.

Add coverage to your build process

The details of setting up coverage within your build process depend on which tools you are using. In our example below we use:

• Composer, as a package manager
• PHPUnit with Xdebug, to execute the tests, and 
• GitHub Actions to perform the build.

 Simply add the following to your ci.yml file: 

- name: Setup PHP with Xdebug
          uses: shivammathur/setup-php@v2
          with:
            php-version: '8.1'
            coverage: xdebug
            
        - name: Install dependencies with composer
          run: composer update --no-ansi --no-interaction --no-progress
          
        - name: Run tests with phpunit/phpunit
          run: vendor/bin/phpunit --coverage-clover=coverage.xml

The resulting file should look something like this: 

.github/workflows/CI.yml

name: CI

on:
  - pull_request
  - push
  
jobs:
  tests:
      name: Tests

      runs-on: ubuntu-latest
      
      steps:
        - name: Checkout
          uses: actions/checkout@v2
          with:
            fetch-depth: 0
          
        - name: Setup PHP with Xdebug
          uses: shivammathur/setup-php@v2
          with:
            php-version: '8.1'
            coverage: xdebug
            
        - name: Install dependencies with composer
          run: composer update --no-ansi --no-interaction --no-progress
          
        - name: Run tests with phpunit/phpunit
          run: vendor/bin/phpunit --coverage-clover=coverage.xml
          
        - name: SonarQube Scan
          uses: SonarSource/sonarqube-scan-action@v4
          env:
            SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

First you install all your project dependencies using Composer as a package manager and then invoke PHPUnit with XDebug to run your tests and generate a coverage report file. 

The essential requirements are that the tool produces its report in the clover.xml format and writes it to a place from which the scanner can then pick it up.

Add the coverage analysis parameter

The next step is to add sonar.php.coverage.reportPaths to your analysis parameters. This parameter must be set to the path of the report file on GitHub Actions produced by your coverage tool. In this example, that path is set to the default produced by GitHub Actions.  It is set in the sonar-project.properties file, located in the project root:

sonar-project.properties

sonar.projectKey=<sonar-project-key>
sonar.organization=<sonar-organization>

sonar.php.coverage.reportPaths=coverage.xml

Wildcards and a comma-delimited list of paths are supported. See Test Coverage Parameters for details.