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.

[wildworks]

What is the reason to backport the patch to 6.9? It looks like it's something related to local development.

[SirLouen]

Replying to wildworks:

What is the reason to backport the patch to 6.9? It looks like it's something related to local development.

I found out that these things are easily backported because if you need to work on such version you have the fix handy available. Same when the env:install was improved last year: You had a faster env:install for branch related topics backported.

But it could not be backported also, its kind of optional. Personally I rarely use minor versions on development, so its superniche but I saw that Weston like to backport this kind of tool patches :)

[jorbin]

If we backport it, I think this may be best backported all the way to 4.7 so that the env functions the same on all versions recieving security updates

[desrosj]

Replying to wildworks:

What is the reason to backport the patch to 6.9? It looks like it's something related to local development.

In general, the goal is always to keep the underlying build tools and environments as consistent as reasonably possible across all branches eligible to receive security updates. This ensures contributors can switch branches to test how a bug was introduced, how something behaved differently, etc.

I don't have strong feelings around how far to backport this one. I lean towards backporting to 6.9 only for now as that branch is actively supported and using xDebug to investigate a problem is more likely. Unless something is broken, tooling-related changes are typically backported together to avoid creating noise unnecessarily. I'm not sure that there are any other changes to backport at this time. We could always include this the next time there is a grouped backport.

Someone would need to go back to 4.7 and verify that the changes work as expected on both platforms before we can consider going back past 6.9, though.

[jorbin]

Happy to defer to @desrosj since he's done more work on the local env. Let's just go to 6.9.

Since this is a bug that affects Windows, I am going to defer to a committer using Windows to do the review for backport.

[wildworks]

In general, the goal is always to keep the underlying build tools and environments as consistent as reasonably possible across all branches eligible to receive security updates. This ensures contributors can switch branches to test how a bug was introduced, how something behaved differently, etc.

Thanks for the detailed explanation.

Since this is a bug that affects Windows, I am going to defer to a committer using Windows to do the review for backport.

In my environment (WSL2 on Windows 11), the problem never occurred in the first place, but the change looks good.

This is off topic, but should we gitignore .vscode/launch.json?

[jorbin]

This is off topic, but should we gitignore .vscode/launch.json?

No. Ignoring individual developer tools can quickly balloon. For people using git, they can ignore can use .git/info/exclude to ignore files related to their tools and for people using svn there is the global-ignores svn configuration file.

[wildworks]

Re-opening for backport consideration.

Approve backport to the 6.9 branch.

[wildworks]

This ticket was brought up in today's 6.9.1 bug scrub, and if there are no objections, I will make a backport commit to the 6.9 branch.

[wildworks]

In 61541:

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

Reviewed-by wildworks.
Merges [61461] to the 6.9 branch.

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