[Configure XDebug, Visual Studio Code for a Vagrant VM] #debug #vm #vscode #masscode

instructions.md

Configure XDebug, Visual Studio Code for a Vagrant VM

1. Assumptions

• Project (Drupal) is served on /var/www/html in the Vagrant box
• Local project files location: c:\Users\username\Work\projects\my-project\repo\html
• Guest machine IP is 10.0.2.2 (if this doesn't work, run route -nee in the VM and look for the gateway address)

2. Configuration

2.1. Install XDebug

• If the extension is not currently installed (run php -i | grep xdebug in the VM and check the output), follow instructions in https://xdebug.org/docs/install

2.2. Configure XDebug

Check the location of your php.ini (in this case located at /etc/php/7.0/apache2/php.ini) file and add/change the following configuration:

xdebug.remote_enable = true
xdebug.remote_autostart = true
xdebug.remote_host = 10.0.2.2
xdebug.remote_port = 9000
xdebug.remote_log = /var/log/xdebug.log
xdebug.max_nesting_level = 1000

After setting this, remember to restart the webserver: sudo service apache2 restart.

2.3. Install XDebug extension for VSCode

Install PHP Debug extension and reload/restart VSCode.

2.4. Configure Debugger in VSCode

1. Switch to the debugger panel
2. Click the gear icon at the top and add a PHP configuration.
3. This will open ./vscode/launch.json file in the editor. Add an entry with the following settings:

{
  "type": "php",
  "request": "launch",
  "name": "Listen for XDebug",
  "pathMappings": {
    "/var/www/html": "${workspaceRoot}\\html",
  },
  "port": 9000,
  "log": true,
}, 

Be careful setting the path mappings or the debugger will not work. This is critical for the extension to work.

NOTE: Once you got the debugger working you could set log value to false to avoid displaying the debug console in VSCode.

2.5. Install an XDebug helper for your browser

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

Here you have some for Chrome or Firefox.

Alternatively, you could add the ?XDEBUG_SESSION_START=vscode parameter to the URL to achieve the same but is a little annoying to be adding this manually in each URL you visit.

3. 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 pallete.
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!

This was very helpful. Thanks!

I had trouble getting this to work until I used forward slashes in the pathMappings in launch.json
"pathMappings": { "/var/www/project/docroot": "${workspaceRoot}/docroot" },

Also, with DrupalVM in your config file you can use
php_xdebug_remote_host: "{{ ansible_default_ipv4.gateway }}"

Thanks v. much for this guide @sveggiani. I've been struggling with this for days. The only change I hafd to make for my setup was

${workspaceRoot} is now deprecated, os I used ${workspaceFolder}. Also the server side of the mapping cannot contain symlinks, at least on my setup: macOS, vagrant, virtualbox.

Thanks again.

Is there any potential that support for the use of symlinks in the pathMappings arg could be added? We use symlinks to map our project folder to the server 'location' in vagrant on our dev boxes, and I believe this is what's causing my current issue of not being able to get breakpoints to hit after the debugger appears to successfully connect to xdebug.

FWIW -- the remote host can vary. I have found the following value to work well for my xdebug.remote_host value. Used multiple times in ubuntu 16 & 18.

route -nee | head -3 | tail -1 | awk '{print $2}'

Vagrant will output something similar to: 10.0.0.2 and docker will output something similar to 172.17.0.1

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

Thank you very much for this guide. Struggled to get this to work but was finally able to. In case this is of any help, these are the settings for our specific case. Running MacOS, vagrant, php7.1; drupal installed at /project with web root being /project/docroot. VS Code workspace root is /project.

php.ini

[XDebug]
xdebug.remote_enable = 1
xdebug.remote_autostart = true
xdebug.remote_host = 10.0.2.2
xdebug.remote_port = 9000
xdebug.remote_log = /var/log/xdebug.log
xdebug.max_nesting_level = 1000

launch.json:

        {
          "type": "php",
          "request": "launch",
          "name": "Listen for XDebug",
          "pathMappings": {
            "/var/www/project/docroot": "${workspaceRoot}/docroot",
          },
          "port": 9000,
          "log": false,
            "xdebugSettings": {
                "show_hidden": 1
            }
        },

It works like a charm. Thank you for this tutorial.

Just a side note for who is using it in multi-root workspaces: The path mappings should include the root folder after VS $workspaceFolder variable, so , the configuration will be like below:

 "pathMappings": {
          "/var/www/Server/": "${workspaceFolder:Server}",
},

Where the workspace include the root folder "Server". Hope that this tip helps someone using this tutorial.

Reference

Thanks @jameswpm your info was helpful in getting this setup. I would like to see the part after the first set of brackets also. I find setting up debugging for vagrant to be a vaguely covered topic most of the time. I will add to this so others can benefit (see video). If anybody has questions about my setup or anything else I can help with don't hesitate to ask. Thank so much, everyone.

http://pctechtv.com/extra/forum/github/190621vphpdbvsc/vagDebgVSC.mp4

@pctechtv. I agree with you about the gap on Xdebug/Vagrant topic. This one here is a excellent exception.

Below is the my complete config for reference:

{
    "name": "Listen for XDebug - Workspace",
    "type": "php",
    "request": "launch",
    "port": 9000,
    "pathMappings": {
        "/var/www/Server/": "${workspaceFolder:Server}",
        "/var/www/Client/": "${workspaceFolder:Client}"
     },
     "log": false
}

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

Thank you. I had the same error and your solution is work for me.

Also you can found host ip using this
netstat -nr | grep '^0\.0\.0\.0' | awk '{print $2}'

What worked for me was in the DrupalVM config.yml setting:

php_xdebug_default_enable: 1
php_xdebug_coverage_enable: 0
php_xdebug_cli_disable: no
php_xdebug_max_nesting_level: 256
php_xdebug_idekey: VSCODE
php_xdebug_remote_enable: 1
php_xdebug_remote_autostart: 1
php_xdebug_remote_connect_back: 1
php_xdebug_remote_host: "{{ ansible_default_ipv4.gateway }}"
php_xdebug_remote_port: 9000
php_xdebug_remote_log: /var/log/xdebug.log

And in VSCode using this launch config:

{
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "pathMappings": {
        "/var/www/drupalvm/drupal": "${workspaceFolder}",
      },
      "port": 9000
}

Then set a breakpont in web/index.php and open a browser at "drupalvm.test" with one of the above XDebug Helper plugins enabled.

Thank you for instructions.
Hope my experience can be helpful. I use vscode, phpdebug, homestead.
I set up remote debugging, but breakpoints didn't work. However exceptions and xdebug_break() worked. VSCode was able to track sourcecode for exceptions and xdebug_break().
I spent about a day trying to figure out what's wrong with my setup. Finally I found out that my pathMappings in launch.json were wrong. I didn't specify drive letter for windows path. "pathMappings": {"/home/vagrant/projects/project1": "/Users/myname/projects/project1"}
Here's my working configuration:

 {
    "name": "Listen for XDebug on Homestead",
    "type": "php",
    "request": "launch",
    "pathMappings": {
        "/home/vagrant/projects/project1": "c:/Users/myname/projects/project1"
    },
    "port": 9003,
},

UPD: ${workspaceFolder} also worked fine, so

 {
    "name": "Listen for XDebug on Homestead",
    "type": "php",
    "request": "launch",
    "pathMappings": {
        "/home/vagrant/projects/project1": "${workspaceFolder}"
    },
    "port": 9003,
},

For xdebug 3:

zend_extension=xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.discover_client_host = true
xdebug.client_host = 10.0.2.2
xdebug.client_port = 9000
xdebug.log = /data/log/xdebug.log
xdebug.idekey = vscode