docs: auto-enable/disable Xdebug when step debugging with VS Code

[jameswilson]

The Issue

Turning Xdebug on and off with ddev is a cheap operation:

ddev xdebug [on|off]

Cheap, but also expensive, in that I often forget to one or both of these tasks when Step Debugging with Visual Studio Code (docs).

It would be nice to automatically execute the shell command ddev xdebug [on|off] when starting and stopping the “Listen for Xdebug” command inside Visual Studio Code. This would remove extra steps, breaking context, as well as avoiding accidentally leaving it on after finishing a debugging session.

How This PR Solves The Issue

This PR updates the Step Debugging docs for Visual Studio Code (docs) with the following:

• Introduce a step to create the .vscode/tasks.json where the ddev xdebug on|off commands are housed.
• Add a preLaunchTask and postDebugTask step to the existing .vscode/launch.json configuration snippet provided by docs.
• Provide a tasks.json snippet file with DDEV docs from which to copy/paste the new configs.
• Remove the manual step of requiring to turn on Xdebug with ddev xdebug on.

Manual Testing Instructions

1.- Setup

Follow the complete steps as modified in this PR, copied here for ease of use,

1. Install the PHP Debug extension.
2. In the menu, choose Run → Open Configuration and add the “Listen for Xdebug” configuration snippet to the project’s .vscode/launch.json.
3. In the menu, choose Terminal → Configure tasks → Create task.json from template → Others and add the “DDEV: Enable Xdebug” and “DDEV: Disable Xdebug” task snippet to the project’s .vscode/tasks.json.
4. Set a breakpoint in your index.php. If it isn’t solid red, restart.
5. In the menu, choose Run → Start Debugging. You may have to select “Listen for Xdebug” by the green arrowhead at the top left. The bottom pane of VS Code should now be orange (live) and should say “Listen for Xdebug”.
6. In a browser, visit your project and confirm you hit the breakpoint.

For step 2 and 3, use the following snippets, again copied from the PR here for ease of use:

.vscode/launch.json:

{
    // See https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
    // for the documentation about the launch.json format
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "hostname": "0.0.0.0",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "preLaunchTask": "DDEV: Enable Xdebug",
            "postDebugTask": "DDEV: Disable Xdebug"
        }
    ]
}

.vscode/tasks.json:

{
  // See https://go.microsoft.com/fwlink/?LinkId=733558
  // for the documentation about the tasks.json format
  "version": "2.0.0",
  "tasks": [
    {
      "label": "DDEV: Enable Xdebug",
      "type": "shell",
      "command": "ddev xdebug on"
    },
    {
      "label": "DDEV: Disable Xdebug",
      "type": "shell",
      "command": "ddev xdebug off"
    }
  ]
}

2.- Test

Between step 4 and step 5 confirm that Xdebug is off, by typing in your terminal ddev xdebug status (result should say "xdebug disabled").

At step 5, confirm that VS Code's Terminal shows the following output, indicating that the step debugger was able to find and execute the task:

 *  Executing task: ddev xdebug on 

Enabled xdebug
 *  Terminal will be reused by tasks, press any key to close it. 

At step 6, confirm that VS Code hits the breakpoint set in index.php, and step debugging works, as normal. At this time you can also go manually check in terminal to confirm that Xdebug is on with ddev xdebug status (result should say "xdebug enabled").

When finished step debugging, tap the red block to Stop debugging in VS Code. The Terminal window should display the following:

 *  Executing task: ddev xdebug off 

Disabled xdebug
 *  Terminal will be reused by tasks, press any key to close it. 

Finally, confirm that Xdebug is actually off, by manually typing into your terminal the following command: ddev xdebug status. The status should be disabled.

Related Issue Link(s)

This came about in a support request thread on the Ddev Discord server:

https://discord.com/channels/664580571770388500/1203038681322102804

Related VS Code docs:

https://code.visualstudio.com/docs/editor/debugging#_launch-configurations
https://code.visualstudio.com/docs/editor/tasks#_custom-tasks

Release/Deployment Notes

Not applicable

[rpkoller]

Left two comments in regards of the wordmark and as already noted on Discord. The spellchecker is already green on the spellcheck step. xdebugand DDEV are listed in the spellcheckwordlist.txt. So technically that are two false positives? Shouldn't the spellchecker failed and required changes already? and the other detail on step-debugging.md is only a minor nitpick to make the wording consistent between the docs page and the json file. and overall a real handy approach. i've already successfully tested. works like a charm thank you!

[rfay]

Looks like it should be great. @ultimike could you please take a look?

[ultimike]

Looks very useful. I didn't test it out yet, but I do have some thoughts:

1. I realize this is a VSCode thing, but I find it odd that the task label is used as the unique identifier between the launch.json and the tasks.json file. Granted, this is irrelevant to this PR.
2. I wonder if there's an opportunity for something like this to be integrated in https://github.com/ddev/vscode-ddev-manager as well (cc @biati-digital).
3. I will share this with our Drupal module development students - and probably walk through its implementation with them later this week during our office hours. I'll report back with any feedback.
4. I'm sure others are feeling this way, but now I'm curious if something similar can be done for PhpStorm...

-mike

[biati-digital]

@ultimike The extension already starts/stops XDebug and creates/updates the launch.json when you select "XDebug Enable" in the project so the functionality it's there and can be adjusted.

We can update the extension to use this method and remove "XDebug Enable" from the menu (see secreenshot).

I'll include this in the next update.

[tyler36]

Works well.

Tested with VSCode 1.86 on using WSL extension with workspace-level launch.json and user-level tasks.json.

[jameswilson]

@rpkoller I've re-requested your review to get this one transitioned to the "Approved" status. Thanks.

Edit: also, it appears review from ddev/documentation is pending. Since this team is not public, is there someone else is that needs to be pinged specifically for review?

[rfay]

@biati-digital if there's anything we need to change from the DDEV end when you look at this, just say so
@ultimike absolutely looking forward to feedback from you and your students.

[rfay]

Nice work @jameswilson , thanks for this great contribution!

[ultimike]

Funnily enough, the first test with did with this in class was using Lando - but all worked as expected!

[rfay]

The preLaunchTask and postLaunchTask here don't work unless you have the DDEV vscode extension, so those will need to be commented out.

Ooops, I missed the step of installing the tasks.json. Gotta read the docs!

[jameswilson]

@rfay I also noticed that the VS Code extension integration seems incomplete, in that it installs (or updates?) the .vscode/launch.json with the preLaunchTask and postLaunchTask, but it doesn't install the new dependencies from .vscode/tasks.json. As you noted, it does work if you manually create the tasks.json but this is kind of a head scratcher that the extension tries to automate some of this but doesn't get it all.

So maybe this does needs a follow-up? Who is/are the maintainers of the VS Code extension, and where should we file an issue?

[rfay]

Thanks @jameswilson - Please file issue at https://github.com/ddev/vscode-ddev-manager

[jameswilson]

Aha, someone already filed an issue for this a few weeks ago:

ddev/vscode-ddev-manager#18

[biati-digital]

@jameswilson The extension does create the tasks.json file. If it's not working for you maybe there's some kind of bug that I'm not able to replicate. We'll continue the conversation in the extension repo. (Please note that I'm currently busy with work so it could take me some time to reply)

[rfay]

(in my case above I wasn't using the extension, I just didn't read the docs to know/remember about the tasks)