Configure Xdebug, Visual Studio Code for a Vagrant VM

vagrant-vscode-php-xdebug-instructions.md

0. Assumptions

• You've installed Xdebug in your VM.
• You've installed Xdebug extension for VSCode and reloaded/restarted VSCode.
• You have not forwarded port 9000 from the guest to the host.
• Configure Debugger in VSCode. See item 1 next.

1. Configure .vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/vagrant/www": "${workspaceFolder}/www/"
            },
            "port": 9000,
            "log": true,
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Note: ${workspaceRoot} is deprecated, use ${workspaceFolder}. Also note that the first part of the mapping cannot contain symlinks. Change from /var/www/html/www to /vagrant/www/

2. Check xdebug.ini

Located at /etc/php/7.0/mods-available/xdebug.ini

Should contain:

zend_extension=xdebug.so
xdebug.remote_enable = 1
xdebug.remote_connect_back = 1
xdebug.remote_port = 9000
xdebug.max_nesting_level = 512
xdebug.remote_autostart = true
xdebug.remote_host = 10.0.2.2
xdebug.remote_log = /var/log/xdebug.log

If you're not sure about the remote.host, execute route -nee on the VM and look for the gateway:

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    0      0        0 enp0s3   0     0      0
10.0.2.0        0.0.0.0         255.255.255.0   U     0      0        0 enp0s3   0     0      0
192.168.33.0    0.0.0.0         255.255.255.0   U     0      0        0 enp0s8   0     0      0

Or

route -nee | awk '{ print $2 }' | sed -n 3p
10.0.2.2

Note: I believe xdebug.remote_host is added automatically, but double check:

$ php -i | grep xdebug.remote_host
xdebug.remote_host => 10.0.2.2 => 10.0.2.2

Also check that the xdebug.so is loaded:

$ php -m | grep -i xdebug
xdebug
Xdebug

3. Install an Xdebug helper for your browser

These helpers allow to enable or disable Xdebug instead of setting cookies or URL parameters by yourself.

Here's one for Chrome and one for Firefox.

4. Debugging

1. Switch to the Debugger panel and press "Start debugging" button (looks like a green play button at the top). You can also run Debug: Start debugging in the commands palette.
2. Set a breakpoint in the file/line where you want to pause the execution clicking to the left of the line number in the editor. You'll see a gray (unverified) or red (verified) dot.
3. Make sure the helper is active (usually in green) or add the URL parameter, and load the page/script in which you set the breakpoint. At this point the page should remain "loading" and the VSCode window become active.
4. Happy debugging!

5. Credits

Heavily inspired by @sveggiani, indeed this is a fork of his gist. Thank you Sebastián.

Thank you so much for putting this together, this got me 90% of the way there for a ubuntu 18.04 user who uses VVV (varying vagrant vagrants) to manage my VM, firefox, and VS Code.

A couple other tips for users who are struggling to get it set up, this is what worked for me, given my above setup, some may be specific to VVV.

• try setting xdebug.remote_host= "vvv.test" (for VVV users, set this in vvv/config/php-config/xdebug.ini )

• I put the absolute paths for the path mappings in launch.json
  e.g.

    	"pathMappings": {
            "/srv/www/plain/public_html": "/path/to/my/vvv/www/plain/public_html"
          },
  

The disadvantage of this is that if you work with multiple websites, you'll have to change this for each one.

• Not already obvious, but you may need a browser extension (chrome or firefox) to begin monitoring. I think this may depend on your vagrant setup. (ref: https://davidsword.ca/troubleshooting-xdebug-config-on-vvv-using-vs-code/).
  I use https://github.com/BrianGilbert/xdebug-helper-for-firefox for firefox.

And most importantly, ensure that your IDE KEY is set properly.
The IDE KEY doesn't need to be configured within VS Code (unlike phpstorm). In my case, the IDE KEY is configured in the preferences in your browser's add-on that you're using.
Using VVV (varying vagrant vagrants), the IDE KEY is already preset to "VVVDEBUG" with (you can confirm this by placing phpinfo(); in a php file of the site you're developing); it should return the IDE Key used by xdebug. when you visit it in your browser. If you're not using VVV, you could you use this way to find out if the IDE KEY is already set to another value and you may need to manually set the IDEKEY in your xdebug.ini to something else as @jsanchezL did

You need to then go into your add-on's preferences and here, you set the IDE key to VVVDEBUG. If you're aren't using vvv, you may need to change this to something else.

UPDATE March 2021: xdebug3 is now out (https://xdebug.org/docs/upgrade_guide) and has some changes from v2; most notably the default port number has changed.