Revisiting GitLab as a PHP Developer
Tags: php, gitlab
Published: 2022-08-18 08:54:00

Every now and then it seems like a good idea to re-read the documentation of tools you've been using for years. In most cases you just update to the latest version and everything works fine, but you may not be using the latest features.

So here are some things I already knew, and some things I newly discovered when I re-read GitLab's documentation after stumbling over this tweet:

{% embed https://twitter.com/s_bergmann/status/1461648425884303364 %}

## TLDR

You may see all of the below in action in this [demo merge request](https://gitlab.com/realFlowControl/php-demo/-/merge_requests/3).


## Unit test reports

The first thing I found is that GitLab has support for the JUnit XML file format and PHPUnit is able to write a JUnit XML file report. By configuring PHPUnit to create a JUnit XML and by declaring this an artefact in `.gitlab-ci.yml` you can have a nice unit test overview in the pipeline itself and the merge request.

![Test summary of your tests, including number of failed and total tests](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/698avj6foimimt4zsgul.png)
 

Add the JUnit logging to your `phpunit.xml` file:
```xml
<phpunit>
    <!-- ... -->
    <logging>
        <junit outputFile="junit.xml" />
    </logging>
    <!-- ... -->
</phpunuit>
```
And tell GitLab-CI via the `.gitlab-ci.yml` about this report:
```yaml
Unit Tests:
  stage: test
  script:
    - ./vendor/bin/phpunit
  artifacts:
    reports:
      junit: junit.xml
```

What you get is a nice overview of the tests run, the time it took to run every single one in the pipeline and in the merge request overview page.
 
You may find more hints about this feature in the [unit test reports](https://docs.gitlab.com/ee/ci/testing/unit_test_reports.html) section of the official GitLab docs.

## Test code coverage

GitLab can show you the code coverage in percent you have with your tests at various places:
- as a badge via a predefined URL
- in a merge request, also indicating if merging this code would increase or decrease code coverage
- and as a nice graph over time in the **Analytics** > **Repository** overview per project and on a group level

![Overall test code coverage including if this MR will raise or decrease code coverage](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hpo874v4j1mxzmycw1hd.png) 

Add a simple coverage report to `phpunit.xml`:
```xml
<phpunit>
    <!-- ... -->
    <coverage>
        <report>
            <text outputFile="php://stdout"
                  showUncoveredFiles="false"
                  showOnlySummary="true" />
        </report>
    </coverage>
</phpunuit>
```
And tell GitLab-CI via the `.gitlab-ci.yml` about this report (add the `coverage` key):
```yaml
Unit Tests:
  stage: test
  script:
    - XDEBUG_MODE=coverage ./vendor/bin/phpunit
  coverage: '/^\s*Lines:\s*\d+.\d+\%./'
```

This assumes you are using Xdebug and have it already installed in the image your are using to run the tests in GitLab CI. Find the [documentation about this feature here](https://docs.gitlab.com/ee/ci/pipelines/settings.html#add-test-coverage-results-using-coverage-keyword).

## Test code coverage visualization

This one was an absolut blast for me. While you are gathering code coverage to have a line coverage number you can see everywhere in GitLab, you can also create a line coverage report as Cobertura XML file format with PHPUnit that GitLab can read and show you covered and uncovered lines directly in the merge requests diff view.

![Diff view with hints if line is covered or not](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/658zheke4d5o36cyh0j4.png)
 

Add a the cobertura coverage report to `phpunit.xml`:
```xml
<phpunit>
    <!-- ... -->
    <coverage>
        <!-- ... -->
        <report>
            <!-- ... -->
            <cobertura outputFile="cobertura.xml" />
        </report>
    </coverage>
    <!-- ... -->
</phpunuit>
```

And tell GitLab-CI via the `.gitlab-ci.yml` about this report (add the `coverage_report` artifacts key):
```yaml
Unit Tests:
  stage: test
  script:
    - XDEBUG_MODE=coverage ./vendor/bin/phpunit
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: cobertura.xml
```

Read more about this awesome feature in the [test coverage visualization](https://docs.gitlab.com/ee/ci/testing/test_coverage_visualization.html) documentation alongside some screenshots.

## Code style violations

[PHP CS Fixer](https://cs.symfony.com/) is able to generate a GitLab formatted report which GitLab can use to show you any new violations in the code or even if code style violations have been tackled.

Run PHP CS Fixer with the `--format=gitlab` argument and tell GitLab CI via the `.gitlab-ci.yml` where the report is to be found:
```yaml
Coding guidelines:
  stage: static analysis
  script:
    - ./vendor/bin/php-cs-fixer fix -v --dry-run --format=gitlab --using-cache=no src/ > gl-cs-fixer.json || exit 0
  artifacts:
    reports:
      codequality: gl-cs-fixer.json
```

I hope this small overview helps you get more out of GitLab and GitLab CI when working with PHP projects.