Tooling
Continuous integration
Adding Phaenon to a pipeline: the steps, a complete GitHub Actions workflow and GitLab CI job, what to cache, and a Dockerfile that ships the compiled PHP.
A Phaenon project's pipeline is a PHP project's pipeline with a few steps changed. composer install brings the compiler and builds the outputs; the checker's findings go on the pull request;
PHPUnit and PHPStan run on the outputs as before, and what they report goes through phn trace so
that it points at .phn lines.
The steps
composer install. Thephaenon/phnplugin installs the binarycomposer.lockpins asvendor/bin/phn, then builds every root when Composer writes the autoloader. A type error stops the install, after the findings are printed.vendor/bin/phn check --format=github(orcheckstyle): the findings, as annotations on the.phnlines. Run it after a failed install too, which is when it has something to say.vendor/bin/phn fmt --check: Phaenon's layout and your php-cs-fixer style, each change reported at its.phnline (Formatting and fixers).- PHPStan on the outputs, its
githuborcheckstylereport throughphn trace. - PHPUnit on the outputs, its output and its JUnit and coverage reports through
phn trace.
An application needs no phn build step: the install has built the outputs. A project that sets
"extra": {"phaenon": {"build": false}} runs vendor/bin/phn build after the install instead. A
library that commits its outputs adds the check that they are current
(Publishing a library).
phn trace exits with 0 whatever it reads, so each step that pipes into it sets pipefail, and
the step keeps the status of PHPStan or PHPUnit.
GitHub Actions
.github/workflows/ci.yml:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
coverage: pcov
tools: composer:v2
# Composer's cache holds the package archives and, under phaenon-phn/,
# the phn binary the plugin downloads.
- name: Find Composer's cache
id: composer-cache
run: echo "dir=$(composer config cache-dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v4
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: composer-${{ runner.os }}-${{ hashFiles('composer.lock') }}
restore-keys: composer-${{ runner.os }}-
# The plugin brings the pinned vendor/bin/phn and builds src/ and tests/.
- name: Install
run: composer install --no-interaction --no-progress
# Also after a failed install: the plugin's build stops the install on
# a type error, and this step puts the findings on the pull request.
- name: Type check
if: ${{ !cancelled() }}
run: vendor/bin/phn check --format=github
- name: Layout
run: vendor/bin/phn fmt --check
- name: PHPStan
run: |
set -o pipefail
vendor/bin/phpstan analyse --no-progress --error-format=github | vendor/bin/phn trace
- name: PHPUnit
run: |
set -o pipefail
php -d pcov.directory=. vendor/bin/phpunit --log-junit junit.xml --coverage-cobertura cobertura.xml | vendor/bin/phn trace
- name: Reports on the .phn lines
if: ${{ !cancelled() && hashFiles('junit.xml') != '' }}
run: |
vendor/bin/phn trace < junit.xml > junit.phn.xml
vendor/bin/phn trace < cobertura.xml > cobertura.phn.xml
- uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: reports
if-no-files-found: ignore
path: |
junit.phn.xml
cobertura.phn.xmlThe workflow assumes the project's PHPUnit, PHPStan and php-cs-fixer configurations point at the
outputs (phaenon.json).
- Annotations. GitHub shows an annotation only on a file the repository holds. The checker's
findings name the
.phn; PHPStan's name the compiled file, which is not in the repository, so they go throughphn traceor GitHub drops them. A traced annotation names its file from the root of the git repository, which also holds for a project in a subdirectory. - Coverage.
-d pcov.directory=.makes PCOV measure the outputs: left to itself it pickssrc/, where the.phnare, and every count comes out 0.
GitLab CI
GitLab reads JUnit reports and Cobertura coverage, both after phn trace. It has no report type
for Checkstyle, so the checker's and PHPStan's Checkstyle files are kept as artifacts for another
tool to read. .gitlab-ci.yml:
test:
image: php:8.5-cli
variables:
# Kept between jobs: the package archives, and the phn binary under phaenon-phn/.
COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache"
cache:
key:
files:
- composer.lock
paths:
- .composer-cache/
before_script:
- apt-get update && apt-get install -y --no-install-recommends git unzip
- curl -sSLf -o /usr/local/bin/install-php-extensions https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions
- chmod +x /usr/local/bin/install-php-extensions
- install-php-extensions pcov @composer
script:
# The plugin brings vendor/bin/phn and builds src/ and tests/.
- composer install --no-interaction --no-progress
- vendor/bin/phn check --format=checkstyle > phn-checkstyle.xml
- vendor/bin/phn fmt --check
- set -o pipefail; vendor/bin/phpstan analyse --no-progress --error-format=checkstyle | vendor/bin/phn trace > phpstan-checkstyle.xml
- set -o pipefail; php -d pcov.directory=. vendor/bin/phpunit --log-junit junit.xml --coverage-cobertura cobertura.xml | vendor/bin/phn trace
after_script:
- vendor/bin/phn trace < junit.xml > junit.phn.xml
- vendor/bin/phn trace < cobertura.xml > cobertura.phn.xml
artifacts:
when: always
paths:
- phn-checkstyle.xml
- phpstan-checkstyle.xml
reports:
junit: junit.phn.xml
coverage_report:
coverage_format: cobertura
path: cobertura.phn.xmlphn trace writes a Cobertura report's <source> as the project's root and every filename from
there, src/Inventory.phn, which is how GitLab matches the coverage to the files of a merge
request.
What to cache
Cache Composer's cache directory, composer config cache-dir, keyed on composer.lock. Besides
the package archives it holds the phn binary the plugin downloaded, under
phaenon-phn/<version>/, about 9 MB; with the cache warm, the install fetches nothing. A cache of
cache-files-dir alone keeps the archives but not the binary.
Do not cache .src/ and .tests/. Checking and compiling a code base of 800 files takes about a
second and a half on a laptop, and an output restored from another commit is the staleness a build
exists to rule out.
Why there is no setup action
Many languages ship a setup-… action that puts the compiler on the runner. Phaenon does not need
one: the Composer plugin already puts vendor/bin/phn into every checkout that runs composer install, at the version composer.lock pins, checked against the SHA-256 the plugin carries. A
second installation step could put another release on the PATH than the one the lock pins, and
the job would check with one compiler and build with another. Call vendor/bin/phn in the
pipeline, and the compiler is the one your developers use.
Building an image
Build where Composer runs, and ship the outputs. The plugin compiles the roots when Composer
writes the autoloader, so the build stage copies phaenon.json and src/ before the dump:
# Build where Composer runs: the phaenon/phn plugin compiles src/ into .src/
# when the autoloader is written.
FROM composer:2 AS build
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-autoloader --no-scripts --no-interaction --no-progress
COPY phaenon.json ./
COPY src ./src
RUN composer dump-autoload --no-dev --classmap-authoritative \
&& rm vendor/phaenon/phn/bin/phn
# Ship the outputs: plain PHP, with the .phn beside them for the line maps.
FROM php:8.5-cli
WORKDIR /app
COPY --from=build /app /appWith a .dockerignore:
.git
vendor
.src
.tests
testscomposer install --no-autoloaderbuilds nothing; thedump-autoloadthat follows builds, before Composer writes its class map, so--classmap-authoritativefinds the outputs.--no-scriptsdoes not skip the plugin.- Leave
tests/out of the build context. The plugin builds every root the tree has, and a production install has no PHPUnit, so the build oftests/would fail onunknown class PHPUnit\Framework\TestCase. A root missing from the tree is skipped, so the samephaenon.jsonserves both. - Leave local outputs out (
.src,.tests), so the image holds what the build stage wrote. - The binary is for the platform Composer runs on: the plugin downloads the Linux build for the build stage's architecture. Nothing in the running image calls the compiler, so the build stage removes it, and the final stage, which copies the stage's tree, never gets it.
- The
.phnship beside the outputs, so thatphaenon/debug's Sentry integration can show their lines (Line maps and debugging). phaenon/phnstays underrequire, notrequire-dev, since this--no-devinstall is where the outputs are built.