Skip to content

[TASK] Add PHP 8.6 preview images on Debian trixie and Alpine - #594

Draft
Kanti wants to merge 1 commit into
webdevops:masterfrom
andersundsehr:ccr-0d93296f-2pkfit
Draft

Kanti wants to merge 1 commit into
webdevops:masterfrom
andersundsehr:ccr-0d93296f-2pkfit

Conversation

@Kanti

@Kanti Kanti commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

⚠️ Do not merge yet: upstream workarounds

This PR stays a draft until every workaround below is gone. Each one is marked TODO PHP 8.6 in the templates and tests.

Breaking changes (PHP 8.6 images only)

  • No vips and xmlrpc. Both are abandoned upstream and do not build against PHP 8.6; the 8.2–8.5 images keep them. Migration notes are in docs/images/php.md: jcupitt/vips 2.x via FFI (with php.ffi.enable: "true" for PHP-FPM), and a userland XML-RPC library.
  • No ionCube Loader, also not later. The images install ionCube only up to PHP 8.5, also once ionCube supports PHP 8.6: 30-setup-ioncube.sh skips it from PHP 8.6 on, before the download. Today it would not work anyway: the ionCube loader for thread-safe PHP needs Zend signals, which the official ZTS images are built without (undefined symbol: zend_signal_globals_offset). Applications that need ionCube stay on PHP 8.5.
  • Debian 13 (trixie) instead of Debian 12, because GD in PHP 8.6 requires libavif >= 1.0.0.
  • Thread safe (ZTS), no pecl/pear, no built-in mbstring in the official images (remove zts, instead all images are always built as zts (8.6+) docker-library/php#1686, Drop --with-pear with PHP 8.6 docker-library/php#1654). mbstring is compiled with oniguruma.
  • max_execution_time counts waiting. Thread-safe PHP measures max_execution_time (PHP_MAX_EXECUTION_TIME) with Zend Max Execution Timers, as elapsed time: time spent in sleep(), waiting for an HTTP response or for exec() counts, and PHP stops the script with the fatal error once the call returns. Up to PHP 8.5 only the time PHP itself runs counts. Documented in docs/images/php.md and docs/environment-variables.md.

Changes

  • New tags: php, php-dev, php-nginx, php-nginx-dev, php-apache and php-apache-dev with 8.6 (Debian 13) and 8.6-alpine. Their Dockerfile.twig files match the 8.5 ones apart from the base image and distribution='trixie'; conf/console.yml sets Debian 13 for the image tests of 8.6.
  • Templates: template/Dockerfile/images/php.twig handles the trixie package names and the 8.6 differences; php-extensions.twig has the PIE list for 8.6, the protobuf patch, vips/xmlrpc up to 8.5 and the helper macros amqpCheckout and xdebug for the 8.6 workarounds.
  • Image tests: ImageUnderTest::hasVipsAndXmlrpc() (like hasImap(), with a unit test in ci/tests) limits vips and xmlrpc in PhpModules to PHP 8.2–8.5. ImageUnderTest::hasIonCube() (Debian up to PHP 8.5, also with a unit test) drives the new PhpChecks::testIonCubeLoaderUpToPhp85OnDebian(), which checks that the Debian 8.2–8.5 images load the ionCube Loader and that the Alpine images and PHP 8.6 have none. ImageUnderTest::isThreadSafe() (PHP 8.6 and later, with a unit test) drives PhpChecks::testPhpThreadSafety() and PhpEnvironmentChecks::testPhpMaxExecutionTimeCountsWaitingOnlyInThreadSafePhp(). The sleep request of the test page takes time_limit=0, which the tests of FPM_REQUEST_TERMINATE_TIMEOUT, FPM_PROCESS_MAX and WEB_PHP_TIMEOUT use, so that PHP_MAX_EXECUTION_TIME=1 does not end their requests first on 8.6. PhpChecks has the 8.6 minimum version and accepts release candidates for 8.6 only. tests/structure-test/php/test.yaml checks vips and xmlrpc for PHP 8.5 and older only.

Changes that also affect the 8.2–8.5 images

These avoid new distribution or version switches in the templates:

  • The nginx.org and Tideways apt repositories use signed-by keyrings instead of apt-key, which trixie no longer has, and nginx.org is used over HTTPS. This fixes the known issue Package sources in the Debian Nginx images, so its entry is removed from docs/known-issues.md.
  • bind9-dnsutils and libfreetype-dev replace the transitional packages dnsutils and libfreetype6-dev.
  • libc-client packages are only installed for PHP 8.2/8.3, which need them for imap.
  • 30-setup-ioncube.sh, which every PHP image contains, has the new version check; the 8.2–8.5 images still install ionCube, as the new image test confirms.
  • The oniguruma packages and the memcached runtime library are installed explicitly. On trixie, libmemcached11t64 would otherwise be removed together with the dev packages.
  • The runtime library list is a single trixie/bookworm block, and the vips/xmlrpc steps are grouped (order only).

SonarCloud

The quality gate fails because SonarCloud counts the generated files of the new 8.6 tags (docker/**/Dockerfile, docker/**/conf/**, workflow jobs) as new code. Almost all findings are identical in the 8.2–8.5 files (installer pipes, unpinned actions, shell style). The curl calls this PR adds (nginx.org and Tideways keys, Blackfire Alpine probe) enforce HTTPS (--proto '=https' --proto-redir '=https'). Excluding the generated files from the analysis is a separate change.

Documentation

The 8.6 details are in docs/images/php.md (section PHP 8.6 (preview)); the README lists the tags, and CONTRIBUTING.md notes that Vips and XML-RPC are only built up to PHP 8.5. Each documented change and the check that confirmed it:

Documented change Check
README, docs/images/php*.md: tags 8.6 / 8.6-alpine, base images, Debian 13 Tags match the -t "webdevops/..." lines of the generated workflow; /etc/debian_version is 13.7, /etc/alpine-release is 3.24.4
php.md: ZTS, no pecl php -v shows (ZTS), command -v pecl pear finds nothing (Debian and Alpine); image test testPhpThreadSafety
php.md, environment-variables.md: in 8.6, max_execution_time counts waiting time With set_time_limit(1), sleep(3), file_get_contents() of a response that takes 3 s and exec('sleep 3') end with Maximum execution time of 1 second exceeded in php:8.6 and php:8.6-alpine; php:8.5 completes all three and stops only busy code. Image test testPhpMaxExecutionTimeCountsWaitingOnlyInThreadSafePhp checks it through PHP-FPM; php-fpm -i shows the default 300
php.md: extension table with an 8.6 column: vips, xmlrpc, ionCube missing in 8.6; lexbor, uri present php -m in php:8.6 and php:8.6-alpine
php.md: ionCube only on Debian up to PHP 8.5, not in 8.6 and later testIonCubeLoaderUpToPhp85OnDebian passes on the published php:8.5 (ionCube Loader v15.5.1) and php:8.5-alpine and on all 12 8.6 images, and fails when php:8.5 is tested with the 8.6 expectations; a Debian 8.5 build of this branch still installs ionCube
php.md: FFI only on CLI and preloading by default, php.ffi.enable for PHP-FPM php-fpm -i shows ffi.enable => preload, and On with the variable; an HTTP request to php-nginx:8.6 returns the result of an FFI call
php.md: no Tideways, Xdebug 3.6 pre-release in -dev php -m in all six -dev images; Xdebug 3.6.0alpha1
known-issues.md: nginx package sources entry removed php-nginx:8.5 and php-nginx:8.6 built from this branch: no sources.list, no trusted.gpg, an appended backports line works and apt-get update prints no warnings (the published php-nginx:8.5 shows the issue)
known-issues.md: Alpine 3.20 repository also applies to 8.6-alpine /etc/apk/repositories in php:8.6-alpine contains the v3.20 line
known-issues.md: Composer 1 deprecations also on 8.6 COMPOSER_VERSION=1, composer --version prints deprecation notices on 8.6
docs/README.md: diagram lists php:8.6-rc-fpm-trixie —
README banner generated with ci/console generate:readme-banner, part of make generate (shows bookworm: 8.2–8.5; trixie: 8.6)

Verification

Checked locally in a sandbox on 8.6.0RC7 (amd64):

  • make generate produces no further diff. All existing workflow jobs are unchanged; there are 24 new 8.6 jobs. make check passes.
  • All 12 PHP 8.6 images build: php, php-dev, php-nginx, php-nginx-dev, php-apache and php-apache-dev, each for Debian trixie and Alpine.
    • php -m runs without warnings, and every module of the image tests' list is present.
    • The dev images load Xdebug and Blackfire.
    • nginx and Apache serve PHP through PHP-FPM, also in a container without IPv6.
  • Image tests: ci/console test:image passes for all 12 PHP 8.6 images (local builds as --reference): 140 to 203 tests per image, no failures; the skipped tests (e.g. 2 for php:8.6, 5 for php:8.6-alpine) are the same as for the 8.5 images. With the changed tests, the published php:8.5, php:8.5-alpine, php-nginx:8.5 and php-apache:8.5 pass as well.
  • The tests/structure-test suites were replayed with a small local runner (the container-structure-test binary was not available); all differences also show up for the published 8.5 images in that runner.
  • Limitation: the sandbox cannot reach api.github.com. For the local build, mongodb was built from its 2.5.7 tag instead of via PIE; the PIE path is the same as on 8.5.

@github-advanced-security github-advanced-security AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SonarCloud found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

@Kanti
Kanti force-pushed the ccr-0d93296f-2pkfit branch 2 times, most recently from 72792ba to 860f23f Compare November 12, 2026 20:44
Add webdevops/php, php-dev, php-nginx, php-nginx-dev, php-apache and
php-apache-dev 8.6 (Debian and Alpine) based on the official PHP 8.6
release candidate images.

- Debian 8.6 uses trixie: GD in PHP 8.6 needs libavif >= 1.0.0, which
  bookworm does not ship. PHP 8.2-8.5 stay on bookworm.
- The official 8.6 images no longer bundle mbstring; build it with
  oniguruma.
- vips and xmlrpc are not built for PHP 8.6: both are abandoned upstream
  and do not build against 8.6. They remain in the 8.2-8.5 images.
- ionCube is only installed up to PHP 8.5, also once ionCube supports
  newer versions. Its loader for thread-safe PHP needs Zend signals,
  which the official 8.6 images are built without. An image test checks
  the ionCube Loader in the Debian 8.2-8.5 images and its absence in
  Alpine and 8.6.
- Install the memcached runtime library explicitly; on trixie it was
  removed together with the purged dev packages.
- Thread-safe PHP counts the elapsed time, waiting included, towards
  max_execution_time. An image test checks this; the tests of PHP-FPM
  and web server timeouts lift PHP's time limit for their requests.

Temporary workarounds until upstream releases support PHP 8.6 (marked
"TODO PHP 8.6"):
- release candidate base images; the version test accepts RCs for 8.6
- apcu, excimer, memcached, yaml and redis from their development
  branches via PIE
- amqp from the unmerged fix php-amqp/php-amqp#638 (pinned commit)
- protobuf: replace the removed zval_dtor() alias
- Xdebug from the 3.6 pre-releases
- no Tideways in the Debian 8.6 dev images: tideways-php 5.47.0 crashes
  PHP 8.6 (ZTS) on startup
- Alpine dev images install the Blackfire probe directly: `blackfire
  php:install` picks the glibc probe on Alpine with ZTS

Template cleanups that avoid new distribution switches (all Debian images):
- signed-by keyrings for the nginx.org and Tideways repositories instead
  of apt-key (removed in trixie)
- bind9-dnsutils and libfreetype-dev instead of transitional packages
- libc-client packages only for PHP 8.2/8.3 (imap)
- oniguruma packages installed unconditionally
@Kanti
Kanti force-pushed the ccr-0d93296f-2pkfit branch from 860f23f to a791017 Compare November 16, 2026 23:02
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
E Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants