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.

Awesome post, James!
Thank you very much!

Hi guys i need yours help.
I have a VM runs over archlinux and the port 9000 is open in my FireWall, visual studio code + PHP Debug and Xdebug helper on chrome.
I was follow the steps, but i have error this the log xdebug

Log opened at 2019-01-07 03:16:11
I: Checking remote connect back address.
I: Checking header 'HTTP_X_FORWARDED_FOR'.
I: Remote address found, connecting to 127.0.0.1:9000.
W: Creating socket for '127.0.0.1:9000', poll success, but error: Operation now in progress (29).
E: Could not connect to client. :-(
Log closed at 2019-01-07 03:16:11

Thanks for your replies

I have solution a my issue, this configuration works in my archlinux + Vagrant + Visual Studio Code + Chrome + xdebug helper
I was reading the documentation of the others IDE's and insert into the file xdebug.ini the follow lines

xdebug.idekey = "debugit"
xdebug.remote_handler = "dbgp"
xdebug.remote_enable = 1
xdebug.remote_connect_back = 0
xdebug.remote_port = 10000
xdebug.max_nesting_level = 512
xdebug.remote_autostart = true
xdebug.remote_host = 10.0.2.2
xdebug.remote_log = /vagrant/log/xdebug.log

Now the debuggin works, thanks any way

Gotchas for me:

• .vscode/launch.json is in the project directory not your user $HOME/.vscode/launch.json
• if you've somehow installed multiple versions of PHP to check xdebug is enabled, use phpinfo() or make sure make sure the version is specified, e.g. php7.1 -m | grep -i xdebug

Also, I was able to get by with a less detailed configuation and no browser extension:

[IN GUEST/VM] /etc/php/7.1/mods-available/xdebug.ini:

zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_host=10.0.2.2
xdebug.remote_port=9000

$projectDir/.vscode/launch.json:

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

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.