Skip to content

GitLab CI template for PHP

This project implements a generic GitLab CI template for PHP.

⚠️ For now it only supports Composer as dependency manager.

It provides several features, usable in different modes (by configuration).


In order to include this template in your project, add the following to your gitlab-ci.yml:

  - project: 'to-be-continuous/php'
    ref: '2.0.1'
    file: '/templates/gitlab-ci-php.yml'

Global configuration

The PHP template uses some global configuration used throughout all jobs.

Name description default value
PHP_IMAGE The Docker image used to run PHP
⚠️ set the version required by your project
PHP_PROJECT_DIR The PHP project root directory .

Managing PHP extensions

Depending on the PHP image you'll be using, your project might require PHP extensions not already installed/enabled in the image.

For this, you may use the following files (located in PHP_PROJECT_DIR):

  • .php_apt_get containing required system libraries (in a single line),
  • .php_pecl containing required PECL extensions (in a single line),
  • .php_ext containing required PHP extensions (in a single line).

More info in How to install more PHP extensions chapter.

Example: a project requires php-gd and php-zip extensions (themselves requiring libzip-dev and libpng-dev libraries)


libzip-dev libpng-dev


gd zip


php-unit job

This job performs PHPUnit tests.

It is bound to the build stage, and is automatically enabled if a PHPUnit XML configuration file is found in the project (phpunit.xml or phpunit.xml.dist).

It uses the following variable:

Name description default value
PHP_UNIT_ARGS Additional PHPUnit options none
PHP_UNIT_DISABLED Set to true to disable PHPUnit test (if some phpunit.xml or phpunit.xml.dist file unintentionally triggers the build) none (auto based on presence of phpunit.xml or phpunit.xml.dist file)

This job:

⚠️ in order to be able to compute code coverage, your project shall have a (dev) dependency to php-code-coverage.

php-codesniffer job

This job performs a PHP_CodeSniffer analysis of your code.

It is bound to the test stage, and is enabled by default.

It uses the following variable:

Name description default value
PHP_CODESNIFFER_DISABLED Set to true to disable this job none (enabled)
PHP_CODESNIFFER_ARGS PHP_CodeSniffer options --report-summary --report-checkstyle=reports/phpcs-checkstyle.xml --report-code=reports/phpcs-code.txt

You have two options to configure PHP_CodeSniffer for your project:

  • either override the $PHP_CODESNIFFER_ARGS variable with your desired options,
  • or use an XML configuration file located in PHP_PROJECT_DIR (.phpcs.xml, phpcs.xml, .phpcs.xml.dist, or phpcs.xml.dist).

💡 When issues are found, don't hesitate to use phpcbf to automatically fix them. Or even better php-cs-fixer.

SonarQube analysis

If you're using the SonarQube template to analyse your PHP code, here is a sample file.

# see:

# tests report: PHPUnit format
# coverage report: Clover format

More info:

GitLab compatibility

ℹ️ This template is actually tested and validated on GitLab Community Edition instance version 13.12.11