Docker PHP with Xdebug 3 env XDEBUG_MODE doesn't work

Question

I’m trying to config Xdebug 3 in PHP container, and set XDEBUG_MODE env variable to off according with documentation https://xdebug.org/docs/all_settings#mode but xdebug_info() shows that mode=develop. How to fix?

Dockerfile:

FROM php:7.4.11-fpm
…
ENV XDEBUG_MODE=off
ENV XDEBUG_CONFIG=""
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
...

docker-compose.yml:

services:
  php:
    build:
      dockerfile: ${PWD}/.devcontainer/Dockerfile
    image: php-fpm
    environment:
      XDEBUG_MODE: ${XDEBUG_MODE} // off
      XDEBUG_CONFIG: ${XDEBUG_CONFIG}

xdebug info:

php -r 'xdebug_info();'
Version => 3.0.0
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support
Feature => Enabled/Disabled
Development Aids => ✘ disabled
Coverage => ✘ disabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✘ disabled
Tracing => ✘ disabled

                                   PHP                                   
                           Build Configuration                           
Version => 7.4.11
Debug Build => no
Thread Safety => disabled
                                 Settings                                 
Configuration File (php.ini) Path => /usr/local/etc/php
Loaded Configuration File => /usr/local/etc/php/php.ini
Scan this dir for additional .ini files => /usr/local/etc/php/conf.d
Additional .ini files parsed => /usr/local/etc/php/conf.d/docker-php-ext-amqp.ini,
/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini,
Directive => Local Value => Master Value

xdebug.mode => develop => develop

UPDATE:

My case: I use VSCode to debug my app, so I need to turn on Xdebug module only when Xdebug listening is active. Better way to do that is using env XDEBUG_CONFIG and XDEBUG_MODE, because it not require change ini files.

Answer 1

It actually works. I mean: the actual behaviour / final result.

Despite the fact that it shows xdebug.mode => develop the actual features are ALL turned OFF:

Feature => Enabled/Disabled
Development Aids => ✘ disabled
Coverage => ✘ disabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✘ disabled
Tracing => ✘ disabled

---

I've tested it locally on a Windows 10 .. and I see the same:

php.ini has

xdebug.mode = debug

Without XDEBUG_MODE override cmd shows that the debugger is enabled as it should:

Feature => Enabled/Disabled
Development Aids => ✘ disabled
Coverage => ✘ disabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✔ enabled
Tracing => ✘ disabled
...
xdebug.mode => debug => debug

With XDEBUG_MODE override:

C:\Users\Andriy
$ SET XDEBUG_MODE=off

C:\Users\Andriy
$ php -r "xdebug_info();"

...
Feature => Enabled/Disabled
Development Aids => ✘ disabled
Coverage => ✘ disabled
GC Stats => ✘ disabled
Profiler => ✘ disabled
Step Debugger => ✘ disabled
Tracing => ✘ disabled
...
xdebug.mode => debug => debug

---

If I run this command (passing additional Xdebug config param that tells to start debugging straight away):

php -dxdebug.start_with_request=yes -r "xdebug_info();"

then WITHOUT the override it will try to establish the debug connection and WITH override it will not try to do that. That confirms that the override works (at very least here in my environment).

Answer 2

The XDEBUG_MODE environment defined in docker-compose definition is overriding the default value from Dockerfile.

Your way only works if you invoke docker-compose with the --env-file (> docker-compose --env-file=xdebug.env ...)

I guess what you want is to inherit a XDEBUG_MODE you are defining inline or is already present in the terminal/shell environment. In that case you just need to declare the var without any value

services:
  php:
    environment:
      XDEBUG_MODE

and call docker-compose similar to > XDEBUG_MODE=Off docker-compose