PHP 8.5 FPM Xdebug image does not include xdebug extension

[jcconde]

Summary

When generating Magento Cloud Docker with PHP 8.5 and --with-xdebug, the generated fpm_xdebug service includes xdebug in the PHP_EXTENSIONS environment variable, but the underlying PHP 8.5 FPM image does not include the xdebug.so extension.

As a result, the container tries to enable Xdebug, but fails with:

error: 'xdebug' does not exist

This makes Xdebug unusable with the PHP 8.5 FPM image.

This issue is relevant for Adobe Commerce 2.4.9, which is a recent release. At the time of checking, there do not appear to be existing issues opened after the release date that cover this specific PHP 8.5 + Xdebug problem.

Environment

• Adobe Commerce version: 2.4.9
• Magento Cloud Docker version: 1.4.8
• PHP image: magento/magento-cloud-docker-php:8.5-fpm-1.4.8
• Docker Compose service: fpm_xdebug
• Host OS: Ubuntu
• Docker command used:

./vendor/bin/ece-docker build:compose \
  --mode=developer \
  --with-xdebug \
  --no-varnish \
  --host='magento2.docker'

Generated docker-compose.yml

The generated fpm_xdebug service contains xdebug in PHP_EXTENSIONS:

fpm_xdebug:
  hostname: fpm_xdebug.magento2.docker
  image: 'magento/magento-cloud-docker-php:8.5-fpm-1.4.8'
  extends: generic
  volumes:
    - '.:/app:delegated'
  environment:
    - 'PHP_EXTENSIONS=bcmath bz2 calendar exif gd intl mysqli pcntl pdo_mysql soap sockets sysvmsg sysvsem sysvshm zip xsl sodium ftp xdebug'
  networks:
    magento:
      aliases:
        - fpm_xdebug.magento2.docker
  depends_on:
    db:
      condition: service_started

Steps to reproduce

1. Generate Docker Compose using PHP 8.5 and --with-xdebug:

./vendor/bin/ece-docker build:compose \
  --mode=developer \
  --with-xdebug \
  --no-varnish \
  --rmq='4.2-management' \
  --host='magento2.docker'

2. Start the containers:

docker compose down --remove-orphans
docker compose up -d --force-recreate

3. Check the loaded PHP extensions in fpm_xdebug:

docker compose exec fpm_xdebug php -m | grep -E "pdo_mysql|sodium|xdebug"

4. Check the fpm_xdebug logs:

docker compose logs fpm_xdebug

Actual result

fpm_xdebug fails to enable Xdebug because xdebug.so does not exist in the PHP 8.5 FPM image.

The logs show:

error: 'xdebug' does not exist

usage: /usr/local/bin/docker-php-ext-enable [options] module-name [module-name ...]

   ie: /usr/local/bin/docker-php-ext-enable gd mysqli

       /usr/local/bin/docker-php-ext-enable pdo pdo_mysql

       /usr/local/bin/docker-php-ext-enable --ini-name 0-apc.ini apcu apc

Possible values for module-name:

bcmath.so bz2.so calendar.so exif.so ftp.so gd.so gmp.so gnupg.so intl.so mailparse.so msgpack.so mysqli.so oauth.so pcntl.so pcov.so pdo_mysql.so raphf.so redis.so shmop.so soap.so sockets.so sodium.so sysvmsg.so sysvsem.so sysvshm.so tidy.so xmlrpc.so xsl.so yaml.so zip.so

Some of the above modules are already compiled into PHP; please check
the output of "php -i" to see which modules are already loaded.

Notice that xdebug.so is not listed as an available module.

Also, php -m does not show xdebug.

Expected result

When using --with-xdebug, the generated fpm_xdebug container should include and load the Xdebug extension.

Expected output:

pdo_mysql
sodium
xdebug

Additional findings

The PHP 8.4 FPM image works correctly with Xdebug using the same Docker setup.

However, the PHP 8.5 FPM image does not include xdebug.so, so the generated fpm_xdebug service cannot enable it.

PHP 8.5 image

The PHP 8.5 image does not include Xdebug in its PECL installation step:

RUN pecl install -o -f \
  gnupg \
  mailparse \
  msgpack \
  oauth \
  pcov \
  raphf \
  redis \
  xmlrpc-1.0.0RC3 \
  yaml

Because of this, --with-xdebug generates a service that asks PHP to enable xdebug, but the actual extension is not available in the image.

Workaround

A local workaround is to create a custom image for fpm_xdebug based on the official PHP 8.5 FPM image and install a compatible Xdebug version manually.

Example:

FROM magento/magento-cloud-docker-php:8.5-fpm-1.4.8

USER root

RUN pecl install -o -f xdebug-3.5.3 \
    && docker-php-ext-enable xdebug \
    && docker-php-ext-enable opcache || true \
    && docker-php-ext-enable gettext || true

CMD ["php-fpm", "-R"]

Then override only the fpm_xdebug service:

services:
  fpm_xdebug:
    build:
      context: .
      dockerfile: .docker/php/8.5-fpm-xdebug/Dockerfile
    environment:
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9001

Then rebuild:

docker compose build --no-cache fpm_xdebug
docker compose up -d --force-recreate fpm_xdebug web

Possible fix

Add a compatible Xdebug version to the PHP 8.5 FPM image, similar to how it is included in the PHP 8.4 image.

For PHP 8.5, this likely requires an Xdebug version that supports PHP 8.5, such as Xdebug 3.5.x.

Impact

This prevents local debugging with Xdebug when using PHP 8.5 and --with-xdebug.

It is especially relevant for developers testing Adobe Commerce 2.4.9 with PHP 8.5, because some issues may only reproduce under PHP 8.5 and cannot be debugged using the current fpm_xdebug service.