Breaking change in zz-docker.conf

[hrak]

The changes in #1635 are causing some breakage in 8.4.17 due to the removal of this bit from zz-docker.conf:

		echo '[www]'; \
		echo 'listen = 9000'; \

The [www] header no longer being part of zz-docker.conf is invalidating a lot of instructions/Dockerfiles found on the internet that f.e. do something along the lines of

echo 'pm.status_path = /status' >> /usr/local/etc/php-fpm.d/zz-docker.conf

that now results in a

[16-Jan-2026 11:42:05] ERROR: [/usr/local/etc/php-fpm.d/zz-docker.conf:3] unknown entry 'pm.status_path'
[16-Jan-2026 11:42:05] ERROR: Unable to include /usr/local/etc/php-fpm.d/zz-docker.conf from /usr/local/etc/php-fpm.conf at line 3

Because its being interpreted as a global setting instead of a pool setting.

And there seems to be quite a lot of that around

[StevenPyle]

I'm interested to see how this is resolved. I've seen multiple apps break this morning due to build processes expecting the [www] section to exist in zz-docker.conf. On the other hand, we can't assume that it won't be changed upstream as we've seen here.

The "workaround" we've come up with is to create a new file called zzz-custom.conf and add all of our customizations there, using "zzz" in the filename to ensure that it is applied after other .conf files, including zz-docker.conf.

As described in issue #241, I think clearer documentation would help developers coming to this for the first time. Perhaps adding comments to zz-docker.conf indicating that it shouldn't be modified. I can create a PR with that if it's useful.

[yosifkit]

Apologies, we had figured that there might be a Hyrum's Law effect, which is why we gated the change to the next patch release of each version. I am working on a fix that'll keep the [www] line in zz-docker.conf for at least all the current Major.Minor versions of PHP (8.2, 8.3, 8.4, and 8.5). I am debating whether or not to keep this compatibility for 8.6+. I'm also working to update the docs (https://hub.docker.com/_/php, https://github.com/docker-library/docs/tree/master/php) to mention how/where users should put their fpm config; that is an oversight on our part.