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.

Hearsh

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).

Lippizaner

I think the key is this slightly ambiguous sentence in the docs: "You can override xdebug.mode on the command line by setting the XDEBUG_MODE environment variable." The OP took this to mean "you can change the value of xdebug.mode ...", but what it actually means is "you can tell XDebug to ignore xdebug.mode ..." You can actually see this in the source code here: github.com/xdebug/xdebug/blob/… – Delly

@Delly Yep, I completely agree on that. Xdebug docs should definitely be more clear on the way that option (environment variable) works. – Lippizaner

If you can think of a good wording for it, I imagine Derick would be happy to have a PR to edit it: github.com/xdebug/xdebug.org/blob/master/html/docs/include/… – Delly

@Delly I'm not good at wording (can be seen by my answers + considering that English is the 3rd language for me) – Lippizaner

I've submitted a PR. We'll see what Derick thinks of it :) – Delly

And... it's updated :) xdebug.org/docs/all_settings#mode – Delly

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

Denverdeny

While plausible, this probably wasn't the issue. As LazyOne demonstrated, and the docs now clarify, the XDEBUG_MODE environment variable doesn't change the xdebug.mode ini setting, it just takes precedence over it. So the original code appears to have been working fine. – Delly

Of course I use .env file next to my docker-compose to change env vars and docker-compose also automaticly reeds .env – Hearsh