WordPress Core setup does not configure XDebug properly

[jdeep]

The WordPress Core development environment does not include proper Xdebug configuration for debugging from host IDEs like VS Code. While Xdebug is enabled in the PHP container, the client_host setting defaults to localhost, which prevents debugging connections from working when the IDE is running on the host machine.

Steps to Reproduce:

1. Clone the wordpress-develop repository
2. Set LOCAL_PHP_XDEBUG=true in .env to enable Xdebug
3. Run the WordPress instance with instructions given in README.
4. Configure VS Code to listen for Xdebug connections.
5. Set breakpoints in PHP files
6. Visit the WordPress site with Xdebug session enabled

Result:
Breakpoints are not triggered.

Expected:
Breakpoints should be triggered.

[SirLouen]

What system are you using?
I'm on W11 with WSL2 and Ubuntu 24.04 and its working flawlessly.

When you talk about breakpoints, apart from the bps in your ID, I'm assuming you are using either xdebug_break() in code, or passing a XDEBUG_something query var to the browser, or using a extension that injects it, right?

Xdebug uses xdebug.start_with_request=trigger so you must trigger it; it's not perma-running as in regular setups.

[jdeep]

Replying to SirLouen:

What system are you using?
I'm on W11 with WSL2 and Ubuntu 24.04 and its working flawlessly.

I am using MacOS Sequoia (with Orbstack).

When you talk about breakpoints, apart from the bps in your ID, I'm assuming you are using either xdebug_break() in code, or passing a XDEBUG_something query var to the browser, or using a extension that injects it, right?

Xdebug uses xdebug.start_with_request=trigger so you must trigger it; it's not perma-running as in regular setups.

Yup, I am using an extension (Xdebug Helper by JetBrains) in Chrome for the trigger.

[SirLouen]

Replying to jdeep:

I am using MacOS Sequoia (with Orbstack).

Networking in that Orbstack might be the culprit specially if you happen to find that xdebug.client_host=host.docker.internal works for you

Which client are you using to connect to Xdebug?

[jdeep]

Replying to SirLouen:

Replying to jdeep:

I am using MacOS Sequoia (with Orbstack).

Networking in that Orbstack might be the culprit specially if you happen to find that xdebug.client_host=host.docker.internal works for you

Possible. However, after a lot of digging through docs and StackOverflow, I found that this is common issue with XDebug running inside a container. For example, ​PHPStorm's Xdebug client puts xdebug.client_host=host.docker.internal in config as well.

Which client are you using to connect to Xdebug?

I am using PHPDebug (by XDebug.org) extension in VSCode.

[SirLouen]

I am using PHPDebug (by XDebug.org) extension in VSCode.

What is the VSCode you are using?

[jdeep]

Replying to SirLouen:

I am using PHPDebug (by XDebug.org) extension in VSCode.

What is the VSCode you are using?

Version: 1.103.2 (Universal)
Commit: 6f17636121051a53c88d3e605c491d22af2ba755
Date: 2025-08-20T16:45:34.255Z (3 wks ago)
Electron: 37.2.3
ElectronBuildId: 12035395
Chromium: 138.0.7204.100
Node.js: 22.17.0
V8: 13.8.500258-electron.0
OS: Darwin arm64 24.6.0

[SirLouen]

Replying to jdeep:

Version: 1.103.2 (Universal)
Commit: 6f17636121051a53c88d3e605c491d22af2ba755
Date: 2025-08-20T16:45:34.255Z (3 wks ago)
Electron: 37.2.3
ElectronBuildId: 12035395
Chromium: 138.0.7204.100
Node.js: 22.17.0
V8: 13.8.500258-electron.0
OS: Darwin arm64 24.6.0

My bad. I was willing to ask, what is the launch.json file you are using in VSCode.

[jdeep]

Replying to SirLouen:

Replying to jdeep:

Version: 1.103.2 (Universal)
Commit: 6f17636121051a53c88d3e605c491d22af2ba755
Date: 2025-08-20T16:45:34.255Z (3 wks ago)
Electron: 37.2.3
ElectronBuildId: 12035395
Chromium: 138.0.7204.100
Node.js: 22.17.0
V8: 13.8.500258-electron.0
OS: Darwin arm64 24.6.0

My bad. I was willing to ask, what is the launch.json file you are using in VSCode.

Yeah. This is my launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www": "${workspaceFolder}",
                "/var/www/src": "${workspaceFolder}/src",
                "/var/www/build": "${workspaceFolder}/build"
            },
            "hostname": "0.0.0.0",
            "xdebugSettings": {
                "max_children": 128,
                "max_data": 2048,
                "max_depth": 3
            }
        },
    ]
}

[SirLouen]

I've tested it, and it works for me with the Docker host.docker.internal hostname explicitly added in the PHP config.
Your VSCode file looks good to me.

[SirLouen]

I'm starting to have the same issue; I'm not sure why. I remember that I triaged this some months ago, so looking back in my history, I found this.

So basically I've tested it, and I can confirm that this patch solves this problem. ✅

[westonruter]

Xdebug is working for me on a Mac, with and without this patch. Gemini explained to me why it works on a Mac without the patch but it fails on Windows with WSL:

Windows (WSL2): WSL2 runs as a distinct, lightweight Linux Virtual Machine. It has its own IP address and its own "Loopback" interface (127.0.0.1). When Xdebug tries to connect to localhost, it connects to the container's own internal network. Since PhpStorm isn't installed inside the container, the connection fails.

The Fix: host.docker.internal is a special DNS name Docker adds to the container specifically to resolve to the Host's internal IP address.

macOS: While also a VM, Docker Desktop for Mac binds ports and handles networking differently to make it feel more "native." However, relying on localhost here is technically "incorrect" for Docker and often breaks if you change network modes.

Moreover, it suggests an additional "universal" fix:

Instead of forcing your colleague to change their config to host.docker.internal and you keeping localhost, you should both use the Discovery mode. This works on Mac, Windows, and Linux without changing a single line of config.

Change your php.ini (or Xdebug config) to:

# 1. Turn on Discovery
xdebug.discover_client_host = true

# 2. Set client_host as a fallback only (can be left as localhost or host.docker.internal)
xdebug.client_host = host.docker.internal

Why this is better: When discover_client_host is true, Xdebug ignores the client_host setting. Instead, it looks at the incoming HTTP request headers (like $_SERVER['REMOTE_ADDR']) to find the IP address of the computer that sent the request (your computer). It then connects back to that IP automatically.

Summary for your Windows Colleague
Because WSL2 is a real Linux VM, localhost points to the Linux VM, not Windows. You have to use host.docker.internal so the container knows how to route out of the VM and talk to PhpStorm on Windows.

In reading the ​Xdebug docs about discover_client_host, it seems to make sense. Do note there is a warning, however:

Please note that there is no filter available, and anybody who can connect to the webserver will then be able to start a debugging session, even if their address does not match xdebug.client_host.

But since the wordpress-develop environment is local, there doesn't seem to be any concern here.

So should the patch be amended to include xdebug.discover_client_host=true?

[SirLouen]

Replying to westonruter:

Xdebug is working for me on a Mac, with and without this patch. Gemini explained to me why it works on a Mac without the patch but it fails on Windows with WSL:

Yes, xdebug is a bit hateful occasionally. Now I'm testing, and it's working for me without any changes to the php-config.ini file.

I think that adding these two little tweaks, both the client_host and the discover_client_host have proven to fix issues and won't do any harm and will provide more robustness to any run.

[SirLouen]

Improving xdebug discoverability.

[westonruter]

In 61461:

Build/Test Tools: Improve Xdebug cross-platform compatibility.

Updates the Xdebug configuration in the local Docker environment to better support Windows (WSL2) users while maintaining stability for macOS and Linux.

• Enables xdebug.discover_client_host to allow Xdebug to automatically connect back to the IP address listed in the HTTP request headers, ensuring the debugger works reliably regardless of specific network topology.
• Sets xdebug.client_host to host.docker.internal as a fallback for xdebug.discover_client_host. In WSL2 networking, localhost resolves to the container itself rather than the host machine, preventing the debugger from connecting to the IDE; host.docker.internal correctly routes to the host machine across platforms.

Follow-up to [60060].

Props SirLouen, jdeep, westonruter.
See #49953.
Fixes #63979.

[westonruter]

Re-opening for backport consideration.