Update PHP in Docker Without Downtime
By PHP Patch Assurance · Last updated: 2026-10-25 · Plain-text version
Updating PHP in Docker means changing the PHP version a container runs, by pointing its image at a fixed release and rebuilding. Because the new image is built while the old container keeps serving, the swap itself takes seconds, and a failed health check can return traffic to the previous image.
Check what you run now
Find the version and the setup before you change anything: docker exec <container> php -v shows the running release, and the Dockerfile's FROM line shows what the next build will use. Note the SAPI too — an Apache image runs mod_php, an FPM image runs PHP-FPM — because it changes which service restarts.
Pin the fixed release
Point the FROM line at the exact fixed release, for example php:8.3.36-apache. Do not patch from a floating tag such as php:8.3-apache: a floating tag can move under you, so two builds from the same Dockerfile can produce different PHP versions. A pinned tag is reproducible.
Build and verify before the swap
Build the new image while the old container keeps serving — this is where the downtime is saved. Before swapping, run php -v inside the new image and exercise the application against it: the home page, login, and whatever your users touch most. A build that has not been verified is not ready to serve.
Swap, then health-check
Stop the old container and start the new one. The mitbbs.ai php2shell patch swapped in about 10 seconds, and the site answered 200 again about 4 seconds after the new container started. Then run the health checks: version, key pages, error log. The patch is not done until the checks pass.
If the health check fails, roll back
Restart the previous image — which is why you kept it tagged instead of deleting it — and verify again. Rolling back is not admitting defeat; it is the gate working as designed. Diagnose the failure with the old version serving, not with the site down.
What this does not cover
Non-Docker hosts need a different path — see the apt guide. And branches below 8.2 cannot be patched in place at all; see the end-of-life guide.
Check your site free Patch service
This guide pairs with the patch service.
Frequently asked questions
How much downtime does a Docker PHP update take?
The build happens while the old container serves, so the downtime is the swap itself — seconds. The mitbbs.ai php2shell patch swapped in about 10 seconds. A blue-green setup can approach zero; a single-host swap is seconds, not zero.
Do I need to change my code for a patch release?
Patch releases, such as 8.3.35 to 8.3.36, are bug and security fixes, not feature changes, so code changes are rarely needed. Minor and major upgrades, such as 8.3 to 8.4, can break things — test those first.
Can I roll back after the swap?
Yes, if you kept the previous image. Restart it, verify, and you are back. That is why the backup gate comes before the patch, not after.