GitHub Actions for WordPress: check your plugin on several PHP versions

What php -l checks

php -l is PHP’s syntax check (“lint”): it reads a file without running it and reports whether it parses. Because each PHP version has its own syntax rules, running it on several versions tells you whether your code still loads on each of them. We ran it on a small plugin with two files, one of which reads a character with curly braces, on the official PHP builds:

== PHP 7.4
No syntax errors detected in my-plugin/my-plugin.php
No syntax errors detected in my-plugin/includes/shortcodes.php
== PHP 8.0
No syntax errors detected in my-plugin/my-plugin.php
Fatal error: Array and string offset access syntax with curly braces is no longer supported in my-plugin/includes/shortcodes.php on line 3
Errors parsing my-plugin/includes/shortcodes.php
== PHP 8.5
No syntax errors detected in my-plugin/my-plugin.php
Parse error: syntax error, unexpected token "{", expecting "," or ";" in my-plugin/includes/shortcodes.php on line 3
Errors parsing my-plugin/includes/shortcodes.php

On PHP 8.0 and 8.5 the failing file returned a non-zero exit code, so a CI job stops there. Why this syntax fails is in the curly-brace guide.

What it can’t catch

We added a file that calls create_function(), removed in PHP 8.0. php -l passed it on PHP 8.0: “No syntax errors detected”. The call is perfectly valid syntax; it only fails when it runs, with “Call to undefined function create_function()” (the guide). The same goes for every removed function, every changed behaviour, and every deprecation notice.

So php -l is a first gate, not a compatibility check.

A GitHub Actions workflow

The workflow below runs the syntax check of every PHP file on each version, in parallel, using GitHub’s matrix feature (docs.github.com). We show it as written, not as run: it needs a GitHub repository, and the outputs above come from the same php -l command on our own builds.

name: PHP syntax
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        php: ['7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5']
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
      - name: Lint every PHP file
        run: |
          find . -name '*.php' -not -path './vendor/*' -print0 \
            | xargs -0 -n1 php -l > /dev/null

xargs stops with a non-zero exit code when any php -l fails, so the job fails and the pull request shows a red cross. fail-fast: false lets every version finish, so you see all the versions that fail, not just the first.

Completing the gate

For client sites, the third-party plugins are usually not in your repository: check those on the site, as described in testing a PHP upgrade on staging.