fix(php8): prevent OPcache double-load without disabling it on older parents

[lussoluca]

🤖 This was written by an AI agent on behalf of @lussoluca.

Problem

Since e9b6e49 ("feat(php8): add PHP 8.5.7 and refresh image dependencies"), the 8.x image emits at every PHP invocation on some builds:

Cannot load Zend OPcache - it was already loaded

Reproduced on the 8.4.22-fpm-alpine3.24-rootless tag. The 8.4.2 tag (built before that commit) is clean.

Root cause

Commit e9b6e49 added a loader block:

RUN if [ -f "$(php -r 'echo ini_get("extension_dir");')/opcache.so" ]; then \ echo "zend_extension=opcache.so" > /usr/local/etc/php/conf.d/00-opcache-load.ini; \ fi

This fires whenever opcache.so exists (all PHP <= 8.4). Whether that double-loads depends on whether the official php parent already enables OPcache.

The official image started enabling OPcache by default in docker-library/php#1587 "Enable opcache by default", merged 2025-06-25, which adds RUN docker-php-ext-enable opcache to every Dockerfile variant (motivated by the RFC make_opcache_required). The determining factor is whether a given php:<patch> tag was built after that merge — not the Alpine version. Pinned old patch releases keep their pre-merge frozen image; newer patches were rebuilt with the change.

So:

• Parent built post-merge (e.g. php:8.4.22-fpm-alpine3.24) — already loads OPcache via docker-php-ext-opcache.ini; our block adds a second loader → double-load warning.
• Parent built pre-merge (e.g. php:8.3.2-fpm-alpine3.18, php:8.3.15-fpm-alpine3.21, php:8.4.2-fpm-alpine3.21) — does NOT load OPcache; our block is the only loader.
• PHP 8.5 — OPcache is statically compiled, opcache.so is absent, the block never fires; parent loads it statically.

Verified against the official parents:

official parent	ships docker-php-ext-opcache.ini	OPcache loaded by parent
php:8.3.2-fpm-alpine3.18 (pinned, pre-merge)	no	false
php:8.3.15-fpm-alpine3.21 (pinned, pre-merge)	no	false
php:8.4.2-fpm-alpine3.21 (pinned, pre-merge)	no	false
php:8.3-fpm-alpine3.21 (rolling, post-merge)	yes	true
php:8.4.22-fpm-alpine3.24 (post-merge)	yes	true
php:8.5.7-fpm-alpine3.24 (static)	static	true

The two alpine3.21 rows show the split is build-date, not Alpine version.

Why not just delete the block

An earlier revision of this PR removed the block entirely. That regressed OPcache on every build whose parent predates docker-library/php#1587 (currently 8.3.2, 8.3.15, 8.4.2) — verified by building 8.3.15 from that revision: no loader present, extension_loaded("Zend OPcache") → false. The block was not "always redundant"; it was redundant only on post-merge parents.

Fix

Guard the block so it adds 00-opcache-load.ini only when the parent has not already enabled OPcache and opcache.so exists:

RUN if [ ! -f /usr/local/etc/php/conf.d/docker-php-ext-opcache.ini ] \
        && [ -f "$(php -r 'echo ini_get("extension_dir");')/opcache.so" ]; then \
        echo "zend_extension=opcache.so" > /usr/local/etc/php/conf.d/00-opcache-load.ini; \
    fi

This is version- and date-agnostic: it keys off the actual presence of the parent's opcache ini.

Additional cleanup: drop dead opcache.fast_shutdown

8/conf/opcache.ini set opcache.fast_shutdown=1. That directive was removed in PHP 7.2 — fast shutdown became always-on and the option no longer exists. On PHP 8.x it is absent from phpinfo() and ini_get("opcache.fast_shutdown") returns false, so the line is silently ignored dead config. The 8/ image only targets PHP 8.x, so it can never apply. Removed.

Verification

Built from this branch (--build-arg PHPVER=..., --target dist) and checked OPcache state:

version	loader source	php -v warning	extension_loaded	engine active (enable_cli=1)
8.3.15	block fires (opcache.so)	none	true	true
8.4.22	parent docker-php-ext-opcache.ini	none	true	true
8.5.7	static (block skipped)	none	true	true

OPcache stays enabled on every build, the double-load warning is gone, and opcache.ini still tunes it (it carries no zend_extension line).

Assisted-by: claude-code/claude-opus-4-8

[sparkfabrik-ai-bot]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review OPcache on PHP 8.5 After removing the block, verify that OPcache is properly enabled and functional on PHP 8.5 builds. The PR description states OPcache is statically compiled on 8.5, but it should be confirmed that the opcache.ini tuning file still applies correctly and OPcache is active without any additional loader configuration. COPY conf/*.ini /usr/local/etc/php/conf.d/ COPY conf.disabled /usr/local/etc/php/conf.disabled COPY fpm-conf-templates/ /templates/ # Make folders writable for the root group RUN chmod 775 /usr/local/etc/php && \ chmod 775 /usr/local/etc/php/conf.d && \ chmod 775 /usr/local/etc/php-fpm.d && \

[sparkfabrik-ai-bot]

PR Code Suggestions ✨

No code suggestions found for the PR.

[Copilot]

Pull request overview

This PR fixes a PHP 8.x image runtime warning caused by OPcache being loaded twice when the upstream php:<tag> parent already enables OPcache by default, while preserving OPcache enablement for older (pre-change) parents.

Changes:

• Guard OPcache loader creation (00-opcache-load.ini) so it’s only added when the parent image hasn’t already enabled OPcache.
• Remove the obsolete opcache.fast_shutdown directive from the PHP 8 OPcache config.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
8/Dockerfile	Adds a presence-check guard to prevent OPcache double-loading while keeping OPcache enabled on older parents.
8/conf/opcache.ini	Removes a dead OPcache setting that no longer applies to PHP 8.x.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Monska85]

LGTM 👍