VSCode PHP Debug Update November 2023

November 4, 2023

4 minutes read

This is a cumulative update post on changes in the VS Code PHP Debug adapter since last year.

The current version is 1.33.1.

Since it has been so long since the last post, I’ll list the versions and link relevant release issues.

1.27.0 - Variable paging

This was still tracked under May 2022 GitHub issue. This is an issue I wanted to solve for a long time, but it was actually VS Code that did not have the right support. The DAP Variable construct understands tha there are namedVariables and indexedVariables. VS Code - as a DAP client - can handle paging only of indexed variables. So the only solution was to present all variables as such. And as an additional quirk, they can only be paged in increments of 100.

Pagged variables

Within the same build I auto enabled the Xdebug feature breakpoint_include_return_value for Xdebug 3.2 and up.

1.28.0 - envFile support

As part of September 2022 GitHub issue I added a requested feature, to read the environment variables from a file. The setting in launch.json is envFile. This will of course only work locally.

1.29.0 - Xdebug Cloud support

This was part of October 2022 GitHub issue and was a long awaited feature. I had to do a lot of refactoring to implement it as Xdebug Cloud connections behave very differently that traditional Xdebug connections. Here the IDE connects to the cloud and uses this one TCP session, where in normal or proxy environment Xdebug connects to the IDE.

A bugfix release 1.29.1 fixed a bug in envFile handling.

1.30.0 - Skip files while debugging

Part of December 2022 GitHub issue. This was also a feature I wanted to work on for a while, but it just did not come together. It’s parallel to Just My Code debugging found in .NET, Python, Dart/Flutter etc. The idea is that you can simply step through your code, but skip library files. Since Xdebug does not offer any facility to support this efficiently I had to implement it with automatically calling stepInto if the uses steps into library code. The user has to use pattern matching to specify what file they want to skip with skipFiles. Typical setup would be:

  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "skipFiles": ["**/vendor/**", "!**/vendor/my-module/**"],
    }

1.31.0 - URI path mappings

Part of January 2023 GitHub issue. Derick made me aware of people using SSHFS and other remote virtual file system extensions in VS Code to mount the code into their workspace. I had to rewrite the path mapping logic to support paths like ssh://host/path.

A fix release 1.31.1 fixed problems with relative URI paths.

1.32.0 - Ignore exceptions

Part of February 2023 GitHub issue. This is a long outstanding issue that was only partially implemented. Currently VS Code does not have a UI to select or define what Exceptions the debugger should react on. There is some support in the DAP, but none in the UI. The implementation that was done relies on launch.json configuration like this:

  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "ignoreExceptions": [
        "BaseException",
        "\\NS1\\Exception",
        "\\*\\Exception",
        "\\**\\Exception*"
      ]

Bugfix release 1.32.1 fixed a matching issue in exceptions and added improved Xdebug Cloud logging.

1.33.0 - skipEntryPaths

Part of July 2023 GitHub issue. As a feature request I added skipEntryPaths where the user can define if the entry script matches the debugger will immediately disconnect.

As part of this release I also removed the vscode.languages.registerEvaluatableExpressionProvider as it was not supposed to be implemented by a debug extension but rather a language extension. I implemented it in vscode-php-intellisense.

1.33.1 - Editor title run/debug buttons

Altho a bugfix release I re-implemented the quick-launch and quick-debug buttons that are shown on the top right side of the editor. The whey the debugger was launched before was not correct.

Other work

I have spent a lot of time on VS Code PHP IntelliSense that I also inherited from Felix. I added a bunch of smaller features and support for newer PHP versions and also some VS Code specific extensions. As I can only donate so much time I started looking into other free PHP language servers and found Phpactor. I’m currently helping with getting the extension published onto Marketplace.

Conclusion

The work has slowed down a bit as most of the features needed for seamless work are already done. However there are a few thing I still want to work on.

Fixing the copy to clipboard problem
Working on a way to implement Exception filtering
Walkthroughs or wizards to help setup debugging
Eval and watch cache problem

Sadly the sponsorship from New Relic CodeStream ended as they discontinued the program where they sponsored popular open source Extensions. If you use the extension and it makes your life easier consider donating via GitHub Sponsors.

As always, ping me on Twitter or GitHub issues if you have problems or questions.

Damjan Cvetko