VS Code + XDebug 3

I’ve started using VS code very recently, and one of the things I was really thrilled about is the option to use XDebug for PHP inside VS code.

I’m using Vagrant for my development, and that’s why I have to find a way to run it inside Vagrant guest machine.

It turns out that all the tutorials online are for XCode 2, and no matter what I’ve tried it does not work. So – lets start with how to enable XDebug 3 on Visual Studio code.

In my configuration I’m using PHP 7.4, Ubuntu 20, and of course after installing the XDebug (for which to achieve you must do the following):

Installing XDebug on Debian / Ubuntu

$ sudo apt update
$ sudo apt install php-xdebug

And this installs XDebug v.3 for PHP (if you are using configuration similar to mine, or latest dictionaries).

Restart PHP:

$ sudo service php7.4-fpm restart

Check XDebug:

$ php -i | grep xdebug
/etc/php/7.4/cli/conf.d/20-xdebug.ini,
xdebug
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support
           Enabled Features
(through 'xdebug.mode' setting)
xdebug.auto_trace => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3)

Next setup is to proper setup your xdebug.ini – in my case it is located here: /etc/php/7.4/mods-available/xdebug.ini

edit that file

$ sudo vim /etc/php/7.4/mods-available/xdebug.ini

and add the following:

zend_extension=xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port = 9000
xdebug.discover_client_host=1
xdebug.log_level = 0
xdebug.remote_enable=1
xdebug.idekey = VSCODE
xdebug.remote_autostart = 1
xdebug.client_host=10.0.2.2
xdebug.client_connect_back=1

That configuration is for XDebug 3 (it wont work for 2.x ver). Keep in mind that this is for Linux like systems, for Mac / Win xdebug.client_host probably is different.

The above is global configuration – will be available in CLI and FPM PHP. That file is soft linked in the following dirs:

/etc/php/7.4/cli/conf.d/

/etc/php/7.4/fpm/conf.d/

If you need different configurations, just remove the soft link and copy the original file from /etc/php/7.4/mods-available/xdebug.ini

Change the port – this is the only change you have to make, that will help you separate the debugging into the VScode.

For the proper xdebug.client_host ip, if you are not sure, execute the following:

fpm service (if you are using php-fpm):

$ route -nee
Kernel IP routing table
Destination     Gateway         Genmask         Flags Metric Ref    Use Iface    MSS   Window irtt
0.0.0.0         10.0.2.2        0.0.0.0         UG    100    0        0 eth0     0     0      0
0.0.0.0         192.168.43.1    0.0.0.0         UG    100    0        0 eth2     0     0      0
10.0.2.0        0.0.0.0         255.255.255.0   U     0      0        0 eth0     0     0      0

Get the IP form the Gateway column.

Restart your fpm service (if you are using php-fpm):

$ sudo service php7.4-fpm restart

If you are using apache don’t forget to restart it either:

$ sudo service apache2 restart

Check your phpinfo() and see if everything is installed:

Or use console:

$ php -i | grep xdebug

Configuring VS code

XDebug plugin

First thing you need to do is to install xDebug for VS Code, then goto VS and select debug view:

Look for the gear next to selected debug session (top of the screen) and click on it:

It will show in the editor configuration file – launch.json – add the following:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "php",
            "request": "launch",
            "name": "Listen for XDebug",
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}",
                "${workspaceFolder}": "${workspaceFolder}",
            },
            "port": 9000,
            "log": true,
        },
        {
            "type": "php",
            "request": "launch",
            "name": "Listen for CLI",
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}",
                "${workspaceFolder}": "${workspaceFolder}",
            },
            "port": 9001,
            "log": true,
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Where the interesting part is to set "/var/www/html": "${workspaceFolder}", – /var/www/html is where my project is mapped on the Vagrant machine (check my tutorial for setting up Vagrant), and ${workspaceFolder} links to root in my VS code project (my root is the same as the mapped folder, if that is not your case – set it appropriately).

Other interesting thing to have in mind is port 9000 (on the Vagrant machine) if 9000 does not work for you change it (both xdebug.ini and this configuration).

That’s it – you are ready to start your debug session in PHP.

Check out the video:

(Stoil Dobreff)