Xdebug 3 WSL2 VS Code Setup

Xdebug 3 WSL2 VS Code Setup

This tutorial shows how to setup Xdebug 3 in WSL2 (Ubuntu 22.04) and VS Code on Windows 11

Most tips on the web for getting Xdebug to play with VS Code and WSL2 are using the php.ini settings from Xdebug 2, which is no longer supported by Xdebug 3.

let’s start Xdebug 3

First go to the Xdebug Installation Wizard. This page helps you finding which file to download, and how to configure PHP to get Xdebug running.

Next after Xdebug 3 is ready in WSL 2, edit the ini file using nano or vi/etc/php/8.1/cli/conf.d/99-xdebug.iniload the module last with 99.

[xdebug]
zend_extension = xdebug.so
xdebug.start_with_request = trigger
xdebug.mode = debug
xdebug.discover_client_host = 1
xdebug.log = /var/log/xdebug.log
xdebug.client_port = 9003

If you are not familiar with the Linux shell, you can also access the WSL file system from Windows to edit the xdebug.ini file. To do this, enter the following line in the explorer address bar to open the folder in which xdebug.ini is located.

\\wsl.localhost\Ubuntu\etc\php\8.1\mods-available

Note. here “Ubuntu” stands for my WSL instance, change it if necessary. The file 99-xdebug.ini is a symlink and points to xdebug.ini.

VS Code WSL extension

Now reopen the workspace/folder using the Remote – WSL extension. To do this, you can bring them up by pressing F1 to open the Command Palette and typing in WSL, or by selecting the green remote indicator in the lower left corner of the status bar and select “Connect to WSL“. You will probably see the suggestion that the WSL extension should be added, just confirm with yes.

Xdebug 3 WSL2 VS Code remote indicatorXdebug 3 WSL2 VS Code status bar

The WSL extension lets you use VS Code on Windows to build Linux applications that run on the Windows Subsystem for Linux (WSL). You get all the productivity of Windows while developing with Linux-based tools, runtimes, and utilities.

At the bottom right of the terminal pane you can see ports that forwarded to localhost port 9003, so VS Code interacts with Xdebug in WSL.

Xdebug 3 WSL2 VS Code Port Forwarded

Add Xdebug launch configuration

Now add PHP: Listen for Xdebug to the VS Code launch configuration with choose Run -> Open Configurations.

        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "stopOnEntry": true,
            "log": true,
            "pathMappings": {
                "/mnt/c/users/<userID>/documents/ubuntu": "${workspaceRoot}"
            }
        }

This the first section “Listen for Xdebug” is needed. If you want to try out more settings, go to my launch.json here.

VS Code Run and Debug

Open the file for debugging in your browser and open it in VS Code, now go to Run and Debug with hit Ctrl+Shift+D and start Listen for Xdebug F5 or click the green arrow and reload the page from the browser.

Xdebug 3 WSL2 VS Code Setup

  A Chrome plugin called Xdebug helper which let you toggle debugging in chrome. You might want to skip temporarily debugging, it also provides profiling and tracing for Xdebug. This add-on is also available for Microsoft Edge did you can get here.

Finalize Xdebug in WSL

Set the owner rights for the web server to the Xdebug log file.

$ chown www-data:www-data /var/log/xdebug.log

Don’t forget to restart the Apache web server.

$ systemctl restart apache2

Troubleshooting

If something went not as expected, the following commands can be helpful for troubleshooting.

How do I know if Xdebug is running? The next command should show the commonly output.

$ php -v
PHP 8.1.2-1ubuntu2.14 (cli) (built: Aug 18 2023 11:41:11) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.2-1ubuntu2.14, Copyright (c), by Zend Technologies
    with Xdebug v3.2.2, Copyright (c) 2002-2023, by Derick Rethans

Further can be checked that Xdebug is listening and ready in VSCode.

$ netstat -tulpen | grep LISTEN

If Xdebug is set up correctly and running in VS Code, you should see the following output.

tcp      0    0 127.0.0.1:3306       0.0.0.0:*     LISTEN    110     23618    298/mariadbd
tcp      0    0 127.0.0.1:35883      0.0.0.0:*     LISTEN    1000    22932    800/node
tcp      0    0 127.0.0.53:53        0.0.0.0:*     LISTEN    101     17836    134/systemd-resolve
tcp6     0    0 :::9003              :::*          LISTEN    1000    17992    966/node
tcp6     0    0 :::80                :::*          LISTEN    0       19672    299/apache2

Port 9003 in particular should appear with LISTEN.

Check if Xdebug responds on localhost port 9003 and VSCode is ready to answer queries.

$ nc -vz 127.0.0.1 9003
Connection to 127.0.0.1 9003 port [tcp/*] succeeded!

If you get connection refused may VSCode is not listening!

The Xdebug log file provides information about the process activities.

$ tail -f /var/log/xdebug.log

The Windows firewall can also be temporarily deactivated if necessary.

Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

Run as administrator in the PowerShell.

Xdebug 3 and Visual Studio Code

The Lightweight Editor VS Code is a cross-platform editor for developers that differs from integrated development environments (IDE). Like Sublime or Eclipse, Visual Studio Code still supports debugging and autocompletion with IntelliSense. But it does not include integrated compilers and components such as version management.

However, Visual Studio Code makes it possible to adapt the environment (IDE) to the required development workflow. With a variety of extensions, so additional features can be integrated from the marketplace, such as the extension for Connect to WSL and Debug support for PHP with Xdebug. The PHP Hypertext Preprocessor must be provided according to the platform and version.

VS Code open project folder with context menu

VS Code open project folder with right click from explorer context menu

If you develop with VS Code, a project folder is also used in here. VS Code stores the workspace settings in the settings.json file. The setting for the debugger in launch.json under the .vscode folder of the respective project folder.

Open VS Code project folder via explorer context menu

When VS Code is installed, the context menu is automatically expanded, allowing a file to be opened from the Explorer context menu in VS Code. Unfortunately, opening a directory from the context menu was lost. This post shows how to expand the context menu to open folders for VS Code.

VS Code reads the project settings by entering code .in the respective folder. The following registry key can be added. This makes it possible to open the selected project folder in VS Code via the explorer context menu.

Add VS Code context menu to registry

REG ADD HKCR\Directory\shell\Code /ve /t REG_SZ /d "Open" /f
REG ADD HKCR\Directory\shell\Code\command /ve /t REG_SZ /d "%localappdata%\Programs\Microsoft VS Code\Code.exe \"%V\"" /f
REG ADD HKCR\Directory\shell\Code /v Icon /t REG_SZ /d "%localappdata%\Programs\Microsoft VS Code\Code.exe" /f

Copy Paste the lines in a command prompt opened as administrator.

  It may be that your system has’t VS Code installed under %localappdata%\Programs. Make sure you know which path code.exe is installed in and, if necessary, modify the path in the last two lines.

Initially, the previous VS Code versions were not installed from the Microsoft store, but were deployed in Program Files, then add this keys.

REG ADD HKCR\Directory\shell\Code /ve /t REG_SZ /d "Open" /f
REG ADD HKCR\Directory\shell\Code\command /ve /t REG_SZ /d "C:\Program Files\Microsoft VS Code\Code.exe \"%V\"" /f
REG ADD HKCR\Directory\shell\Code /v Icon /t REG_SZ /d "C:\Program Files\Microsoft VS Code\Code.exe" /f

Copy Paste the lines in a command prompt opened as administrator.

The new “Code” context menu is now registered.

Right-click above the selected folder, in the context menu click “Open” at the blue code symbol.

VS Code open project folder with context menu

Note. In Windows 11, under “Show more options” you can find the context menu with the VS Code you just added.

Remarks

The Lightweight Editor VS Code is a cross-platform editor for developers that differs from integrated development environments (IDE). Like Sublime, Atome or Eclipse, Visual Studio Code still supports debugging and autocompletion with IntelliSense. However, it does not include integrated compilers and components such as version management, project management, or the ability to easily create graphical user interfaces (GUI).

However, Visual Studio Code makes it possible to adapt the development environment (IDE) to the required development workflow. With a variety of extensions, VS Code can be expanded in many ways, so additional features can be integrated from the marketplace, such as extensions for version control and debugger tools. The interpreters and compilers of the languages must be provided according to the platform and version.