Auto-build & release workflow for a PHP CLI, powered by static-php-cli + Box — feedback welcome

[GianfriAur]

Hi everyone 👋

I've been experimenting with static-php-cli to ship a small PHP CLI tool as standalone binaries on GitHub Releases, and the result ended up being more solid than I expected — sharing the workflow here in case it's useful to someone else, and looking for feedback / ideas to improve.

Project

php-opcua/opcua-cli — a command-line tool for OPC UA industrial servers (browse, read, write, watch, certificate trust, NodeSet2.xml code generation). The target audience is PLC / SCADA / automation engineers, many of whom don't have PHP installed, so standalone binaries are a big UX win.

What the workflow does

On every v* tag push, .github/workflows/release-binaries.yml:

1. Builds the PHAR once on ubuntu-latest via Box and uploads it as an intermediate artefact.
2. Fans out to 4 matrix legs, each using static-php-cli:
   • linux-x86_64 on ubuntu-latest
   • linux-aarch64 natively on ubuntu-24.04-arm (no QEMU, no cross-compile)
   • macos-arm64 on macos-latest
   • windows-x86_64 on windows-latest (experimental, continue-on-error: true)
3. Each leg downloads the shared PHAR, runs spc doctor/download/build/micro:combine to produce the final self-contained binary, smoke-tests it with --version / --help, and uploads it as an artefact.
4. A release job downloads the 4 binaries, generates SHA256SUMS.txt, and attaches everything to a GitHub Release automatically via softprops/action-gh-release.

Full workflow: https://github.com/php-opcua/opcua-cli/blob/master/.github/workflows/release-binaries.yml

A companion doc with step-by-step manual reproduction (for users who want a binary for a platform we don't ship): https://github.com/php-opcua/opcua-cli/blob/master/doc/04-build-from-source.md

A few things I learned along the way

Most of these ended up as small decisions in the YAML, but each one cost me a failed CI run to figure out 😄 — writing them down in case they save someone else the round-trip:

• PHAR build belongs on Linux, always. I initially had each leg run box compile locally. On Windows it intermittently failed with Failed to remove directory C:\...\box\BoxXXXXXX: Resource temporarily unavailable (Windows releases file handles lazily, Box cleans its temp dir eagerly — box-project/box#1077). Splitting the PHAR into a dedicated build-phar job on Linux and sharing it as an artefact sidesteps the issue entirely, makes the PHAR deterministic across targets, and saves ~1 min per leg.

• GITHUB_TOKEN is not optional on macOS. spc download hammers api.github.com to resolve upstream release tags (zlib, libxml2, openssl, …). On ubuntu-latest I never hit the unauthenticated 60 req/hour limit; on macos-13/macos-latest it failed every run with HTTP 403 and then crashed inside Downloader.php on an empty path. Setting env.GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} at job level makes every spc download call authenticated and the problem disappears.

• Never set defaults.run.shell: bash on Windows. I did this initially so ./spc-src/bin/spc … would work cross-OS. Building Linux / macOS: fine. Building Windows: spc internally shells out to tar -x -C "D:\a\…\source\php-src" and Git Bash interprets the \a / \o / \p as C escape sequences, mangling the path. tar then fails with "No such file or directory" and the build dies with an unhandled TypeError in SourcePatcher. Fix: drop the default shell, invoke SPC as php ./spc-src/bin/spc … (works in bash / pwsh / cmd), and reserve shell: bash for the occasional step that really needs chmod/head/file — Git Bash is pre-installed on windows-latest so it's there when you need it.

• ext-posix is Linux/macOS only. Discovered via SPC\exception\EnvironmentException: builtin extension posix is not supported on Windows platform. Obvious in hindsight. Moved the extension list from a workflow-level env to a per-matrix-row extensions: field so Windows can have its own list (one item fewer).

• macos-13 runner pool is effectively gone. Jobs targeting it park in the queue indefinitely rather than failing fast. Added timeout-minutes: 90 at job level as a safety net — also dropped the macos-x86_64 target from the matrix because Intel Mac native CI isn't realistic on free runners anymore. In practice this means you can no longer natively compile for macos-13 (Intel) on GitHub-hosted free runners — you either need a paid macos-13-large, a self-hosted Intel Mac, or you drop Intel as a distribution target. Users with Intel Macs fall back to composer global require or a local build.

• Native aarch64 runners are a quiet win. ubuntu-24.04-arm runs the exact same spc commands as ubuntu-latest. No --arch=aarch64, no QEMU, no cross-toolchain hassle. First cold build on ARM takes ~30 min, subsequent runs with the SPC cache hot drop to ~5 min, same as x86_64.

What I haven't figured out yet

• Windows remains experimental. The build usually completes now (after the fixes above), but I haven't yet wired in a real end-to-end smoke test on the .exe. My current smoke test runs --version / --help only. Previous attempts to add live smoke via docker-compose failed on the cross-runner matrix (docker on macOS needs colima, docker on Windows defaults to Windows containers, etc.), and I reverted it. Right now the Windows artefact has continue-on-error: true so a broken build doesn't block the Linux / macOS release, but that's a workaround, not a solution.
• macOS binaries are unsigned. Users have to xattr -cr <binary> on first launch to clear Gatekeeper. Adding codesign --timestamp --options=runtime + xcrun notarytool submit --wait is on the roadmap but needs an Apple Developer ID in a GitHub secret.
• No linux-musl target yet. Tempting for Alpine / scratch Docker images but I haven't measured the size difference against the glibc static build.

Question for the community

Does this setup look sane, or am I missing an obvious simplification? In particular:

• Is there a cleaner way to pass GITHUB_TOKEN to spc download than an env var, or is that already the canonical pattern?
• Has anyone gotten Windows spc build to work reliably from a bash-shell CI step, or is cmd/pwsh really the only viable host-shell?
• Any gotchas for adding linux-musl cross-compile that you wish you'd known upfront?

Happy to hear any advice / horror stories / "you're doing X the hard way" comments 🙂

Thanks to @crazywhalecc and the SPC contributors — this project genuinely made it possible to ship a pure-PHP CLI without asking industrial users to install a PHP runtime. Big deal for my target audience.

[crazywhalecc]

Thank you for your feedback. I haven't reviewed your comments in detail yet, but there are three points I'm certain of:

• Regarding shell support on Windows, we explicitly support cmd/pwsh, but it hasn't been tested on Windows bash (mingw). However, we fixed the issue of incorrect tar calls recently, so this is likely no longer a problem.
• Environment variables is the standard custom method. You can also permanently set environment variables by writing a env.custom.ini or adding them to craft.yml.
• You can use ZigToolchain to build any current arch based target you want on Linux, including musl-static, musl-dynamic, glibc, and glibc-2.17. On v2 version, you can switch between them using SPC_TARGET=native-native-gnu.2.17 (see env.ini configuration for details). We will officially abandon the old musl cross-compilation tool in the upcoming v3 release, using zig instead.

Furthermore, regarding the posix extensions you mentioned, I don't have any good ideas at the moment. Also, our own testing process for the macOS x86_64 platform uses the free macos-15-intel, and I also have a Hackintosh on my local machine for testing. I hope this information provides you with some important reference.

[henderkes]

Windows is not posix compliant, it's impossible to make it work.

[GianfriAur]

I expected that, I had already prepared the fallback ConsoleOutput.php#L146, Are there any other more Windows-specific ways or is this okay in your opinion?

[henderkes]

I don't know, I avoid php on windows as best as possible.

[henderkes]

Is there a cleaner way to pass GITHUB_TOKEN to spc download than an env var, or is that already the canonical pattern?

That's the canonical pattern.

Has anyone gotten Windows spc build to work reliably from a bash-shell CI step, or is cmd/pwsh really the only viable host-shell?

No, php itself explicitly only supports cmd and powershell.

Any gotchas for adding linux-musl cross-compile that you wish you'd known upfront?

SPC_TARGET=x86_64-linux-musl spc/build ... and done. If you're going for cli applications that don't need shared extensions, you should just drop glibc builds entirely. Musl targeting static builds can be ran on any linux system.