Configure XDebug, Visual Studio Code for a Vagrant VM

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!