ci: cache the debug PHP image instead of rebuilding it every run

[lisachenko]

The problem

tests-internal-debug is the slow job in this workflow, and the slow part is not the tests. It recompiles PHP from source inside tools/docker/php-debug.Dockerfile on every push and every pull request, once per matrix leg (8.4 and 8.5), to produce an image that is byte-identical to the one the previous run built. Nothing was cached between runs — Docker's layer cache is local to a runner, and every job gets a fresh one.

The change

The finished image is saved with docker save and stored through actions/cache@v6; on a hit it is restored with docker load and the build step is skipped entirely.

The cache key names every input that can change the image:

php-debug-image-<runner.os>-<runner.arch>-<nts|zts>-<php minor>-<hash of the Dockerfile>-<digest of php:<minor>-cli>

• OS + architecture — a debug PHP binary is not portable across either.
• Thread safety — nts today, carried in a job-level PHP_THREAD_SAFETY env var. A ZTS variant would arrive with its own build arg and its own value, so the two flavours could never be handed the same tarball.
• PHP minor — the matrix leg.
• Dockerfile hash — editing the recipe invalidates the entry by itself. There is nothing to bump by hand.
• Base image digest — resolved with docker buildx imagetools inspect --raw, which queries the registry rather than pulling layers the hit exists to avoid downloading. This is what makes a date-based rotation unnecessary: the entry expires exactly when a rebuild would produce something different, instead of rebuilding for nothing or serving a PHP patch older than the rest of the matrix runs on.

No restore-keys, deliberately. This job runs destroy_zend_class() over a copied class entry while its template is live; a prefix near-miss would run that against an image built from a recipe or a base nobody described. Either the exact build is cached or it is rebuilt.

Two guards that go with it

• The tarball is written as image.tar.part and renamed into place. The cache is written by a post step that can still run after a step failed, and a truncated archive stored under the exact key would poison every later run — with the rename, a docker save that dies leaves no cached path at all and nothing is stored.
• The "is this really a debug build" check now also asserts PHP_MAJOR_VERSION.PHP_MINOR_VERSION against the matrix leg. That check used to guard a build that had just happened; it now guards whatever came out of the cache, so an image restored under a key that does not describe it cannot pass quietly.

Effect

A warm run replaces a full PHP compile with a tarball download and a docker load. Entries written by a main run are readable from every PR branch, so the compile is normally paid once per Dockerfile or base-image change rather than once per pull request. A cold run does exactly what it did before, plus one registry API call and the docker save.

Notes

• tests-internal-debug is the only job in any of the repositories reachable from this session that builds a PHP image; every other job uses shivammathur/setup-php, which is already fast. lisachenko/z-engine itself, which this Dockerfile was copied from, is outside this session's repository scope and could not be attached — the same pattern should be applied to its tools/docker/php-debug.Dockerfile job, where an NTS/ZTS matrix makes the thread-safety key component do real work.
• AGENTS.md §6 documents the caching contract so the no-restore-keys rule is not quietly relaxed later.
• Not verifiable from here: the build itself needs a Docker daemon. The workflow YAML parses, every run: block passes bash -n, and the imagetools --raw | sha256sum digest was confirmed against the digest Docker Hub reports for php:8.4-cli. The first CI run is the real check — it will be a cold miss on both legs, and the run after it should show the hit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KBWEmGUKhtVGSwtQ6ixuQT

---

Generated by Claude Code