2020-11-30 12:03

How-to guide write-up provided here: VSCode xdebug drush / command line-based php on Linux

I wanted to share what seems to be successful for me in using xdebug with drush and Microsoft Visual Studio Code Text Editor on Ubuntu 20.04 LTS Linux.

For this, the xdebug setup for ddev and visual studio code is mainly the same: https://ddev.readthedocs.io/en/latest/users/step-debugging/

The only 2 different key things are: the launch.json file and how you would run drush.

My launch.json file is as follows:

  // 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": [
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "stopOnEntry": true,
      "pathMappings": { 
        "/var/www/html/web": "${workspaceRoot}", 
        "/var/www/html/vendor": "${workspaceRoot}/vendor"
      "name": "Launch currently open script",
      "type": "php",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "port": 9000,
      "stopOnEntry": true

And it's location is: myproject/.vscode/launch.json

Where myproject is my top-level project folder.

The "stopOnEntry": true setting was instrumental in determining how to setup the path mappings. Having this setting meant I got meaningful errors when trying to debug, like:


^ And with that error, I was able to determine what my path settings should be.

This launch.json I have is for me to xdebug both PHP on the CLI and on the locally developed website itself.

I have web within myproject folder where my PHP application sits (Drupal 8). web is my docroot in ddev-speak for my PHP application. So my path for web is myproject/web.

And to run drush, you need have drush as part of your codebase (typically installed using composer require drush/drush ):

ddev exec /var/www/html/vendor/bin/drush <command>

where command is a drush command like cr for clear cache, so would look like:

ddev exec /var/www/html/vendor/bin/drush cr

You would want to do this, rather than run ddev's built-in drush.

And it seemed to work, for me so far, setting a break point in drush code and it was hit on running drush.

And you can still use options like -vvvto get more verbose output to show what drush is doing "behind the scenes", e.g.:

ddev exec /var/www/html/vendor/bin/drush -vvv cr

The location of launch.json relative to the top level project folder and web is crucial I think to ensure xdebug works in general.

Further Reading

Also see a troubleshooting contribution I made here:


which includes how to see what the variable values are used in launch.json https://code.visualstudio.com/docs/editor/variables-reference#_how-can-i-know-a-variables-actual-value

Comments welcome

So I hope that helps folks. I didn't see specific xdebug PHP CLI steps for VSCode in the docs so thought I'd contribute.

I'd welcome any feedback or adjustments that can help ensure that xdebugging is consistently, reliable, repeatable and robust. At the moment it seems to be working for me. I'm cautiously optimistic as I've seen pain others have experienced when it doesn't work which makes me angry - after all we are dealing with digital computers here.


  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答


  • weixin_39985820 weixin_39985820 5月前

    Thanks for this!

    Instead of two path mappings, just map /var/www/html to the project and you don't have to map anything else. That's what's shown in the docs, and yours isn't actually correct. You have /var/www/html/web as workspaceroot, and it's not.

    I have been banging my head against the wall about XDebug/VSCode/DDEV (Drupal 9.x) not catching my breakpoints, and this thread helped me understand that my original path mappings were not the issue. I had actually gone to having

    "/var/www/html/web" : "${workspaceRoot}/web"

    and then realized that was completely unnecessary, after reading the comment above. So the docs, as they are, work fine for Drupal 9 where the webroot is in the /web path.

    I did appreciate this comment, as well:

    My launch.json file is as follows: ... And it's location is: myproject/.vscode/launch.json

    Nope, my issue turned out to be that I needed an extra firewall rule. I know the troubleshooting section of the docs mentions firewall rules, but I think maybe this information should be in the basic setup section. On Manjaro Linux (Cinnamon) with a firewall UI tool, I added this:

    Screenshot from 2020-08-13 14-39-14

    and presto, everything works.

    Thanks for DDEV. Working great for me, as someone who hasn't really gotten up and running with Docker.

    点赞 评论 复制链接分享
  • weixin_39603778 weixin_39603778 5月前

    Thanks for all the effort on this!

    点赞 评论 复制链接分享
  • weixin_39603778 weixin_39603778 5月前

    Thanks for this!

    Instead of two path mappings, just map /var/www/html to the project and you don't have to map anything else. That's what's shown in the docs, and yours isn't actually correct. You have /var/www/html/web as workspaceroot, and it's not.

    Life would be easier than this if you enable the drush custom command provided in .ddev/commands/web/drush.example and change the path there to /var/www/html/vendor/bin/drush. Then everything is just ddev drush <command>

    However, my own preference is just to work inside the web container, so ddev ssh and just use drush there.

    点赞 评论 复制链接分享
  • weixin_39603778 weixin_39603778 5月前

    I don't see any mention of you setting up $PHP_IDE_CONFIG, which is usually the first thing somebody needs to do to debug drush, see the same docs. But PHP_IDE_CONFIG will be automatically set in drush v1.15.

    You could also set PHP_IDE_CONFIG in the drush custom command.

    点赞 评论 复制链接分享
  • weixin_39928017 weixin_39928017 5月前

    Thank you acknowledged - I certainly would not want others to use inaccurate help I've provided here. I'll aim to review amy setup and update.

    点赞 评论 复制链接分享