Xdebug not working out of the box

[Jules Colle]

This issue is regarding the ​wordpress-develop repo on github

I expected Xdebug to work out of the box after setting LOCAL_PHP_XDEBUG=true in the .env file, but that wasn't enough.

It looks like I had to add a couple of lines to tools/local-env/php-config.ini as well:

xdebug.remote_enable=1
xdebug.remote_connect_back=1

In my opinion, these lines should be added to php-config.ini by default.

---

Additionally, I have a suggestion to also add some information on how to use Xdebug for WP core development with VS code, as it turns out you also need some custom configuration in the .vscode/launch.json file. I've written an article about this: ​https://bdwm.be/wordpress-core-development-with-xdebug-and-vs-code/

Feel free to quote the article or include parts of it in the WP developer documentation.

[Jules Colle]

Adds 2 lines of configuration, necessary to make Xdebug work in the docker container.

[Jules Colle]

re-added newline at end of file

[johnbillion]

Thanks for the patch and the link to the blog post @jules-colle .

Autostarting the remote debugging and automatically connecting back to the initiating client definitely makes sense for a local development environment.

• The ​Xdebug extension for Chassis enables both of these.
• ​VVV enables remote_autostart but not remote_connect_back.

[pento]

This has the potential to introduce interesting security vulnerabilities, I don't think it should be enabled by default.

Off the top of my head:

• Some Travis PHPUnit tests run with Xdebug enabled. Would this allow remote connections to the Travis job, potentially exposing encrypted keys?
• Xdebug allows arbitrary code execution, if other people are able to connect to someone's development environment (for example, if it's exposed to the local network at a contributor day, or they use a forwarding service like ngrok), this could very easily open a contributor's computer to attack.

I'd be more comfortable with enabling this if it can reliably restrict who it connects to.

This is a follow-up to this topic in 2025

Now that we are using XDebug 3, the original patches were deprecated.
​https://xdebug.org/docs/upgrade_guide

Now the issues that @pento was raising have been resolved since no remote_enable is needed anymore and the integration, is mostly straight forward.

I'm submitting a new patch to enable the setup of Xdebug by default without requiring people to touch this file that is not ignored by .git by default. But Xdebug is not enabled by default since both LOCAL_PHP_XDEBUG=true and LOCAL_PHP_XDEBUG_MODE=debug are required for Xdebug to work, so in this regard, the user is "safe" by deafult.

But having to manually untrack the tools/local-env/php-config.ini file (in a development build, which theoretically Xdebug should be an staple for all developers), doesn't make any sense to me.

Pinging @desrosj as he introduced the latest changes in Xdebug .env. variables
@johnbillion and @whyisjake as they touch this report back in the day.
Maybe it never progressed because of the concerns that @pento raised that are not valid any more.

Trac ticket: https://core.trac.wordpress.org/ticket/49953

[SirLouen]

This is a very trivial update that can get on time for 6.8 RC1
I don't know how devs can have been able to bear without this thing. Unless there is something I'm missing and also works, it is a pain in the stomach.
Raising awareness for any of the build tools maintainers: @netweb @desrosj @SergeyBiryukov @jorbin or @hellofromTonya

[SergeyBiryukov]

In 60056:

Build/Test Tools: Enable starting Xdebug with the PHP request in local environment.

This aims to facilitate setting up Xdebug locally without editing the tools/local-env/php-config.ini file, which is not ignored by Git by default.

Note that this does not enable Xdebug by default, since both LOCAL_PHP_XDEBUG=true and LOCAL_PHP_XDEBUG_MODE=debug are additionally required for Xdebug to work.

Props SirLouen, jules-colle, johnbillion, pento.
Fixes #49953.

[johnbillion]

This has broken the Xdebug tests :(

​https://github.com/WordPress/wordpress-develop/actions/runs/13957652497/job/39073517458

[SergeyBiryukov]

In 60057:

Build/Test Tools: Revert [60056] pending test failure investigation.

See #49953.

I've commited a new patch version, switching to trigger instead of yes:
​https://xdebug.org/docs/all_settings#start_with_request

The problem is that since we are setting mode to debug it will start xdebug during the github tests

With trigger it will only will be executed on trigger (for example, via browser extension to listen to breakpoints, or with xdebug_break). Its less comfy but it should work well with Github Actions.

Trac ticket: https://core.trac.wordpress.org/ticket/49953

[SirLouen]

@SergeyBiryukov I've commited a new patch version, switching to trigger instead of yes:
​https://xdebug.org/docs/all_settings#start_with_request

The problem is that since we are setting mode to debug it will start xdebug during the github tests

With trigger it will only will be executed on trigger (for example, via browser extension to listen to breakpoints, or with xdebug_break). Its less comfy but it should work well with Github Actions.

[SirLouen]

Test Report

Description

This report validates that the indicated patch works as expected.
It's a little weird that I create a testing report for my patch, but this is meant to accelerate the redeployment of this patch to be ready for 6.8 RC1.

Patch tested: ​https://patch-diff.githubusercontent.com/raw/WordPress/wordpress-develop/pull/8554.diff

Environment

• WordPress: 6.8-beta2-59971-src
• PHP: 8.2.28
• Server: nginx/1.27.4
• Database: mysqli (Server: 8.4.4 / Client: mysqlnd 8.2.28)
• Browser: Chrome 134.0.0.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.1
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0

Expected results

Given than the Github action for Xdebug is:

LOCAL_PHP_XDEBUG=true node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit -v --group xdebug --exclude-group __fakegroup__

We expect that running it passes all the tests

Results with the PR 8515

$ LOCAL_PHP_XDEBUG=true node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit -v --group xdebug --exclude-group __fakegroup__

Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml

External HTTP skipped tests can be caused by timeouts.
If this changeset includes changes to HTTP, make sure there are no timeouts.

PHPUnit 9.6.22 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.28
Configuration: /var/www/phpunit.xml.dist
Warning:       Your XML configuration validates against a deprecated schema.
Suggestion:    Migrate your XML configuration using "--migrate-configuration"!

EE                                                                  2 / 2 (100%)

Time: 00:02.659, Memory: 203.00 MB

There were 2 errors:

1) Tests_Ajax_wpAjaxResponse::test_response_charset_in_header
PHPUnit\Framework\Exception: Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).

2) Tests_oEmbed_HTTP_Headers::test_rest_pre_serve_request_headers
PHPUnit\Framework\Exception: Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).
Xdebug: [Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port).

ERRORS!
Tests: 2, Assertions: 0, Errors: 2.

Actual Results with PR 8554

1. ✅ Issue resolved with patch.

$ LOCAL_PHP_XDEBUG=true node ./tools/local-env/scripts/docker.js run php ./vendor/bin/phpunit -v --group xdebug --exclude-group __fakegroup__
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml

External HTTP skipped tests can be caused by timeouts.
If this changeset includes changes to HTTP, make sure there are no timeouts.

PHPUnit 9.6.22 by Sebastian Bergmann and contributors.

Runtime:       PHP 8.2.28
Configuration: /var/www/phpunit.xml.dist
Warning:       Your XML configuration validates against a deprecated schema.
Suggestion:    Migrate your XML configuration using "--migrate-configuration"!

..                                                                  2 / 2 (100%)

Time: 00:02.663, Memory: 203.00 MB

OK (2 tests, 3 assertions)

[SergeyBiryukov]

In 60060:

Build/Test Tools: Enable starting Xdebug on trigger in local environment.

This aims to facilitate setting up Xdebug locally without editing the tools/local-env/php-config.ini file, which is not ignored by Git by default.

Note that this does not enable Xdebug by default, since both LOCAL_PHP_XDEBUG=true and LOCAL_PHP_XDEBUG_MODE=debug are additionally required for Xdebug to work.

Props SirLouen, jules-colle, johnbillion, pento.
Fixes #49953.

[SergeyBiryukov]

Replying to SirLouen:

I've commited a new patch version, switching to trigger instead of yes:
​https://xdebug.org/docs/all_settings#start_with_request

Thanks for the updated patch, it appears that the tests are passing now :)

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

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