GitLab CI template for PHP¶

This project implements a GitLab CI/CD template to build, test and analyse your PHP projects.

For now it only supports Composer as dependency manager.

Usage¶

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/php/gitlab-ci-php@4.8.0
    # 2: set/override component inputs
    inputs:
      image: "registry.hub.docker.com/library/php:8-apache" # ⚠ this is only an example

Use as a CI/CD template (legacy)¶

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/php'
    ref: '4.8.0'
    file: '/templates/gitlab-ci-php.yml'

variables:
  # 2: set/override template variables
  PHP_IMAGE: "registry.hub.docker.com/library/php:8-apache" # ⚠ this is only an example

Global configuration¶

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

Input / Variable	Description	Default value
`image` / `PHP_IMAGE`	The Docker image used to run PHP set the version required by your project	`registry.hub.docker.com/library/php:latest`
`project-dir` / `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_packages 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)

.php_packages:

libzip-dev libpng-dev

.php_ext:

gd zip

Jobs¶

`php-unit` job¶

This job performs PHPUnit tests.

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

It uses the following variables:

Input / Variable	Description	Default value
`unit-args` / `PHP_UNIT_ARGS`	Additional PHPUnit options	none
`unit-disabled` / `PHP_UNIT_DISABLED`	Set to `true` to disable PHPUnit test	none (auto based on presence of `phpunit.xml` or `phpunit.xml.dist` file)

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

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
`$PHP_PROJECT_DIR/reports/php-test.xunit.xml`	xUnit test report(s)	GitLab integration & SonarQube integration
`$PHP_PROJECT_DIR/reports/php-coverage.cobertura.xml`	Cobertura XML coverage report	GitLab integration
`$PHP_PROJECT_DIR/reports/php-coverage.clover.xml`	Clover XML coverage report	SonarQube integration

`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:

Input / Variable	Description	Default value
`codesniffer-disabled` / `PHP_CODESNIFFER_DISABLED`	Set to `true` to disable this job	none (enabled)
`codesniffer-args` / `PHP_CODESNIFFER_ARGS`	PHP_CodeSniffer options	none

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.

In addition to a textual report in the console, this job produces the following reports, kept for one day:

Report	Format	Usage
`$PHP_PROJECT_DIR/reports/php-codesniffer.checkstyle.xml`	Checkstyle code quality	N/A

SonarQube analysis¶

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

# see: https://docs.sonarqube.org/latest/analyzing-source-code/test-coverage/php-test-coverage/
sonar.sources=src
sonar.tests=tests

# tests report: xUnit format
sonar.php.tests.reportPath=reports/php-test.xunit.xml
# coverage report: Clover format
sonar.php.coverage.reportPaths=reports/php-coverage.clover.xml

More info:

`php-sbom` job¶

This job generates a SBOM file listing installed packages using @cyclonedx/cyclonedx-php.

It is bound to the test stage, and uses the following variables:

Input / Variable	Description	Default value
`sbom-disabled` / `PHP_SBOM_DISABLED`	Set to `true` to disable this job	none
`sbom-version` / `PHP_SBOM_VERSION`	The version of @cyclonedx/cyclonedx-php used to emit SBOM	none (uses latest)
`sbom-opts` / `PHP_SBOM_OPTS`	@cyclonedx/cyclonedx-php options used for SBOM analysis	none

`php-outdated` job¶

This job shows the list of installed packages that have updates available (uses composer outdated).

It is bound to the test stage, and can be run manually at will.

It uses the following variable:

Input / Variable	Description	Default value
`outdated-opts` / `PHP_OUTDATED_OPTS`	`composer outdated` options	`--direct`

`php-composer-audit` job¶

This job performs a vulnerability scan in your dependencies with composer audit.