The php-test component#
Every engine gets its own check: this component runs your test command once per supported PHP version. This page shows how to add the php-test component to your app's .gitlab-ci.yml, how the matrix and the cache work, and how to trial the next PHP release. Next, add the composer-audit component.
Include the component#
Goal: your app's test suite runs on each supported PHP version. The component runs the test command on each supported PHP version through parallel:matrix. Add the include to your app's .gitlab-ci.yml:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/php-test@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
test_command: vendor/bin/phpunit
Inputs#
| Input | Type | Default | What it does |
|---|---|---|---|
stage |
string | test |
Pipeline stage for the jobs. |
job_name |
string | php-test |
Name of the job. Set it when you include this component more than once. |
image |
string | php:${PHP_VERSION}-cli-trixie |
Docker image for the jobs. The default carries the literal ${PHP_VERSION}, which GitLab expands in the image at job time. |
image_prefix |
string | ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX} |
Registry path in front of image: the job pulls image_prefix/image. The default is the group's GitLab Dependency Proxy, so Docker Hub is asked once and GitLab serves the cached copy. Outside a group with the proxy, set docker.io. No trailing slash. |
php_versions |
array | ["8.3", "8.4", "8.5"] |
PHP versions to test against. |
php_advisory_version |
string | "" |
One more PHP version tested in a separate <job_name>-advisory job that may fail (allow_failure: true), for example 8.6-rc (follows the newest release candidate) or 8.6.0RC5. Empty: no advisory job. Never add a release candidate to php_versions. |
composer_version |
string | 2.11.1 |
Composer version to install, 2.9.6 or later. |
test_command |
string | vendor/bin/phpunit |
The test command to run. |
working_dir |
string | . |
Directory to run the command in, relative to the project root. |
What the jobs do#
The array input feeds parallel:matrix directly, so one job is created per PHP version. PHP_VERSION becomes a CI/CD variable in each job, which the image input's default expands at job time. The default image is deliberately tag-pinned, so each job runs the newest patch release of its PHP version. Each job is interruptible: true with a timeout: 30 minutes, and its script:
- Installs
unzipandgitwithapt-get, because thephp:*-cliimages do not ship them (the images are Debian-based, soaptis used). - Copies the official Composer installer from
getcomposer.organd verifies its SHA-384 against the signature fetched at runtime fromcomposer.github.io/installer.sig. On a mismatch the check deletes the installer and exits 1. No$variables appear in thephp -rcode, so GitLab CI variable expansion cannot corrupt it. - Runs the installer quietly with
--install-dir=/usr/local/bin --filename=composerand the pinnedcomposer_version, so Composer lands on PATH, then removescomposer-setup.php. - Changes into
working_dirand runscomposer install --no-interaction --no-progress. - Runs
test_command.
Caching#
The jobs always cache Composer downloads in .composer-cache/ so repeat runs do not re-download every package. The cache key is fixed per PHP version, not a composer.lock hash, so a lock change downloads only the packages that changed and each PHP version gets its own cache:
cache:
key: preflight-php-${PHP_VERSION}
paths:
- .composer-cache/
policy: pull-push
variables:
COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
COMPOSER_CACHE_DIR points Composer at a path inside the project so GitLab can cache it.
Try the next PHP release without breaking the pipeline#
Include php-test a second time for the release that is not supported yet, name that job, and let it fail. The name is what lets your own .gitlab-ci.yml loosen only that job:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/php-test@<full commit SHA> # <tag>
inputs:
php_versions: ["8.6"]
job_name: php-test-next
# While 8.6 only has release candidate images, name the tag: php:${PHP_VERSION}-rc-cli-trixie
# image: "php:${PHP_VERSION}-rc-cli-trixie"
php-test-next:
allow_failure: true
A red php-test-next job is an early warning, not a stop. Drop the allow_failure and move the version into the main php_versions list once the release is supported (the supported versions follow policy.json).
Testing the next PHP release#
Set php_advisory_version to a release candidate tag and the component adds a <job_name>-advisory job that runs your tests on that version:
include:
- component: $CI_SERVER_FQDN/enterprise-apps/preflight/php-test@fb73b538f3980292119b5b306ff64383d760a214 # 0.9.0
inputs:
test_command: vendor/bin/phpunit
php_advisory_version: "8.6-rc"
The value goes into the image tag, php:<version>-cli-trixie, so any tag the official php image publishes works:
8.6-rc follows the newest release candidate, and an exact one such as 8.6.0RC5 stays put. The job warns, it never
blocks; move the version into php_versions only once it is a final, supported release.
Preflight's own pipeline runs this job on 8.6-rc against its fixture app. Its first look, on 2026-11-11, found the
8.6 candidate image built without the mbstring extension, which PHPUnit needs, so the job stops before the first
test. That is the point of the job: you hear about it from a yellow warning, well before it could turn a required
job red.