PHP Docker Upgrade

PHP version upgrade in a Docker environment

Bump the PHP runtime of the containers to a target version BEFORE touching the framework/core — otherwise composer update fails or the site won't boot.

Target version is a parameter. Set <PHP_VERSION> to what you need:

• Drupal 11 → 8.4 (current requirement)
• Future majors (e.g. Drupal 12) → 8.5+ — the procedure is identical, only the number changes.

If the caller (e.g. the d11 orchestrator) already fixed the target, use it. Otherwise ask the user which PHP version to target.

Golden rule: everything goes through the Makefile

This project is Dockerized and driven by a Makefile. Never call composer, php or docker directly on the host — use the make targets:

1. Locate the Dockerfile / PHP image

The image is defined either in a dedicated Dockerfile or in docker-compose.yml.

grep -rn 'php:' docker/ 2>/dev/null
grep -rn 'FROM php' docker/ 2>/dev/null
find . -name 'Dockerfile*' -not -path './vendor/*' -not -path './node_modules/*'

2. Update the PHP version

In the PHP service Dockerfile, replace the base image version:

# BEFORE
FROM php:8.3-fpm

# AFTER — <PHP_VERSION>, e.g. 8.4
FROM php:8.4-fpm

If the image comes from a tag in compose:

# docker-compose.yml — php service
image: myregistry/php:8.4-fpm   # instead of 8.3

Verify the PHP extensions installed in the Dockerfile are compatible with the target version (usually yes — double-check pecl / docker-php-ext-* calls).

3. Rebuild and restart

make rebuild                 # rebuild images and restart (with cache)
make rebuild-no-cache        # if the PHP layer doesn't refresh

4. Verify the new version

make shell
# inside the container:
php -v        # should display <PHP_VERSION>.x
exit

# or via drush
make drush c='status' | grep -i php

5. Reinstall dependencies under the new PHP

make install     # composer install + npm install

If Composer complains about a frozen platform.php constraint in composer.json, update it to the target version:

"config": {
    "platform": {
        "php": "8.4.0"
    }
}

then make composer update --lock.

Where this fits in a framework upgrade

The PHP bump is a technical prerequisite, done first. For a full Drupal 10 → 11 upgrade it is step 2, followed by fixing deprecations and jQuery while still on D10, then the core bump last — see the d11 orchestrator skill.