Automate upstream refresh checks for supported PHP Docker images

[g0blin79]

Context

The repository currently maintains a manual matrix of PHP Docker images in config.json and pins upstream PHP, base image variants, and PECL extension versions inside version-specific Dockerfiles.

After adding new PHP versions and refreshing supported branches, we should improve the maintenance workflow so future upstream changes are easier to detect, review, and apply.

Goals

• Define an explicit support policy for maintained PHP branches.
• Detect when supported upstream PHP patch versions change.
• Detect when expected Docker image variants appear, disappear, or change.
• Detect whether PECL extension pins used in Dockerfiles are behind upstream releases.
• Provide a repeatable report that can be run locally and in CI.
• Optionally automate dependency updates with Renovate.

Proposed Policy

Only PHP branches listed as actively supported or security-supported by the official PHP project should remain in the supported image matrix.

Reference source:

• php.net/supported-versions.php

Branches that are no longer supported upstream should be moved out of the active build matrix and documented as unsupported tags.

Proposed Implementation

1. Add an upstream check script

Add a script such as:

• scripts/check-upstream.php, or
• scripts/check-upstream.sh

The script should read the official Docker PHP image metadata from:

• docker-library/official-images/library/php

It should compare that source against this repository's state:

• latest patch versions for supported PHP branches, for example 8.2.x, 8.3.x, 8.4.x, 8.5.x;
• availability of expected variants:
  • apache-trixie
  • apache-bookworm
  • fpm-alpine
• ARG PHP_VERSION values in the Dockerfiles;
• image tags declared in config.json;
• PECL extension pins in Dockerfiles, such as redis, igbinary, oauth, and mcrypt.

The script should produce a clear report showing:

• current repository value;
• upstream value;
• whether the item is up to date;
• suggested action when drift is detected.

2. Add scheduled GitHub Actions coverage

Add a scheduled workflow, weekly or monthly, that runs the upstream check script.

Possible behavior:

• fail with a readable report when drift is detected; or
• open a tracking issue with the report; or
• both, depending on how noisy the check becomes.

The workflow should also be runnable manually via workflow_dispatch.

3. Consider Renovate as the preferred automation path

As a stronger follow-up, evaluate Renovate with custom managers to update:

• ARG PHP_VERSION values in Dockerfiles;
• tags in config.json;
• README tag documentation, if feasible;
• PECL extension pins where reliable upstream sources are available.

Renovate may be preferable because it can open focused PRs with changelog context and avoids turning the check script into a full dependency-update engine.

Acceptance Criteria

• A documented policy defines which PHP branches are supported.
• A local command can report drift between this repository and upstream PHP Docker metadata.
• The check covers PHP patch versions, expected image variants, config.json, Dockerfile ARG PHP_VERSION, and PECL pins.
• A scheduled GitHub Action runs the check and makes drift visible.
• Renovate custom manager feasibility is documented, or Renovate is configured if chosen.

Out of Scope For The First Iteration

• Automatically publishing refreshed Docker images.
• Automatically merging version bumps.
• Supporting PHP branches that are no longer supported upstream.