ToolingContinuous integration

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

  1. composer install. The phaenon/phn plugin installs the binary composer.lock pins as vendor/bin/phn, then builds every root when Composer writes the autoloader. A type error stops the install, after the findings are printed.
  2. vendor/bin/phn check --format=github (or checkstyle): the findings, as annotations on the .phn lines. Run it after a failed install too, which is when it has something to say.
  3. vendor/bin/phn fmt --check: Phaenon's layout and your php-cs-fixer style, each change reported at its .phn line (Formatting and fixers).
  4. PHPStan on the outputs, its github or checkstyle report through phn trace.
  5. 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.xml

The 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 through phn trace or 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 picks src/, where the .phn are, 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.xml

phn 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 /app

With a .dockerignore:

.git
vendor
.src
.tests
tests
  • composer install --no-autoloader builds nothing; the dump-autoload that follows builds, before Composer writes its class map, so --classmap-authoritative finds the outputs. --no-scripts does 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 of tests/ would fail on unknown class PHPUnit\Framework\TestCase. A root missing from the tree is skipped, so the same phaenon.json serves 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 .phn ship beside the outputs, so that phaenon/debug's Sentry integration can show their lines (Line maps and debugging).
  • phaenon/phn stays under require, not require-dev, since this --no-dev install is where the outputs are built.