Xdebug 3.0 WSL2 and VSCode - Configuration That Works

Question

Most examples on the web for getting PHP debugging working with VSCode and WSL use Xdebug 2.x php.ini settings. Those no longer work with version 3.0. See the Xdebug Upgrade for details on changes.

The following worked for me on a PHP project with a single file just to test debugging. Using Ubuntu 20.04, WSL2, Xdebug 3.02 with the VSCode extensions Remote WSL and PHP Debug by Felix Becker.

I had to modify both /etc/php/7.3/apache2/php.ini and /etc/php/7.3/cli/php.ini on my system. Hope this works for you folks.

php.ini

[xdebug]
zend_extension = ./lib/php/20180731/xdebug.so
xdebug.start_with_request = trigger 
xdebug.mode = debug
xdebug.discover_client_host = 1
xdebug.log = /tmp/xdebug_remote.log
xdebug.client_port = 9003

launch.json

"configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "stopOnEntry": true,
            "log": true,
            "pathMappings": 
            {
                "/var/www/html/test": "${workspaceRoot}"             
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]

Martin_W · Answer 1 · 2021-12-13T05:55:36.250

To supplement what @Jim D has documented:

I had originally opened my VSCode WSL2 workspace using its Windows network share path \\wsl$\Ubuntu-18.04\srv\www\myphpwebsite. Xdebug did not work with this configuration—presumably because port 9003 was not being forwarded from Windows to WSL2.

I had to reopen the workspace/folder using the Remote - WSL extension. To do this, you can click the Remote-WSL control on the VSCode status bar (bottom left corner) and choose "Reopen Folder in WSL". It took about 10 minutes to "install" Remote-WSL into WSL2.

Thereafter, I had to "install" (or enable) the PHP Debug extension specifically in the WSL:Ubuntu WSL2 environment, even though it was already installed in VSCode.

My launch.json configuration is:

        {
            "name": "myphpwebsite",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/srv/www/myphpwebsite": "${workspaceRoot}" 
            },
            //"stopOnEntry": true,
            //"log": true,
            "xdebugSettings": {
                "max_data": 10000,
                //"show_hidden": 1,
                "max_children": 250,
                "max_depth": 10
            }
        },

My PHP configuration (for PHP 7.3) is as follows: In the /etc/php/7.3/apache2/conf.d folder, the 20-xdebug.ini file is a symbolic link to /etc/php/7.3/mods-available/xdebug.ini. This was configured automatically via sudo apt install php7.3-xdebug. It contains just:

zend_extension=xdebug.so

Then I added a supplemental 99-xdebug.ini file to the /etc/php/7.3/apache2/conf.d folder (to ensure it loads after the 20-xdebug.ini file, and to keep its configuration separate from the distro). That file contains:

xdebug.mode=debug
xdebug.start_with_request=trigger
;xdebug.start_with_request=yes
xdebug.discover_client_host=1
;xdebug.log=/tmp/xdebug/xdebug.log
xdebug.output_dir=/tmp/xdebug/
xdebug.client_port=9003
xdebug.var_display_max_depth=10
xdebug.var_display_max_children=250
xdebug.var_display_max_data=10000

Don't forget to restart Apache after making .ini changes.

With the xdebug.start_with_request=trigger setting, after launching the debugger in VSCode, I use the Chrome Xdebug helper extension to trigger an XDebug session. (If the .ini setting xdebug.start_with_request=yes is used instead, then the Xdebug helper extension is not needed, since Xdebug will try to connect with a debugger on port 9003 with every web request to PHP.)

Lastly, I commented out the xdebug.log=/tmp/xdebug/xdebug.log setting, since this produces very large verbose logs. (But it was useful in initially diagnosing what was happening.)

UPDATE

To use xdebug.start_with_request=trigger and xdebug.trigger_value=VSCODE with VSCode's "Launch currently open script" debug configuration, I had to set the correct environment variables in an "env" section in launch.json:

        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003,
            "pathMappings": {
                "/srv/www/myphpwebsite": "${workspaceRoot}" 
            },
            //"stopOnEntry": true,
            //"log": true,
            "env": {
                "XDEBUG_MODE": "debug",
                "XDEBUG_TRIGGER": "VSCODE"
            }
        },

Good luck with Xdebugging!

Do you have a documentation link for the change to `env`? GitHub docs still indicate it's `env`: https://github.com/xdebug/vscode-php-debug#supported-launchjson-settings. See "Options specific to CLI debugging" there. — Martin_W, Apr 12 '22 at 18:39

score 0 · Answer 2 · answered Dec 31 '22 at 20:36

Update for PHP 8.1. Needed to change the full path to the xdebug.so file. zend_extension = ... Your path may be different,depending on your system. It is the "20210902" that is different.

[xdebug]
zend_extension = /usr/lib/php/20210902/xdebug.so
....
....

Xdebug 3.0 WSL2 and VSCode - Configuration That Works

2 Answers2

UPDATE

Linked