Add support for environment variables in `pathMappings`

[Tolsee]

Description

Just like how vscode handle environment variables, can we enable pathMappings to support env variables as well?

Launch config would look something like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/${env:YOUR_ID}": "${workspaceFolder}/app"
      },
      "ignore": ["**/vendor/**/*.php"]
    }
  ]
}

[Tolsee]

https://github.com/xdebug/vscode-php-debug/pull/1068

[zobo]

Will look at this asap

[Tolsee]

Thanks @zobo!

[zobo]

The real question here is, why is this not already working? https://code.visualstudio.com/docs/reference/variables-reference#_environment-variables

[Tolsee]

I think the substitution works for values, not the keys as shown in the example

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/${env:YOUR_ID}": "${workspaceFolder}/app"
      },
      "ignore": ["**/vendor/**/*.php"]
    }
  ]
}

It may have worked if we have pathMappings to be of type {local:string;remote:string}[]?

[zobo]

I remembered something about this. I already reported this and provided a patch but not sure what happened to this. https://github.com/microsoft/vscode/issues/245798 https://github.com/microsoft/vscode/pull/245989

I looks like it got merged, but I can't find the code in main.... strange. I need to check this before I merge this patch.

[zobo]

I went back and tested this without your patch. And as it looks to me, things work as they should. This was my launch,json

    {
      "debugServer": 4711, // Uncomment for debugging the adapter
      "name": "Launch currently open script",
      "type": "php",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "port": 0,
      "runtimeArgs": ["-dxdebug.start_with_request=yes"],
      "env": {
        "XDEBUG_MODE": "debug,develop",
        "XDEBUG_CONFIG": "client_port=${port}"
      },
      "ignoreExceptions": ["IgnoreException"],
      "pathMappings": {
        "/var/www/${env:YOUR_ID}": "${workspaceFolder}/app"
      },
      "log": false
    },

And when I debugged what I get from VSC to the adapter on launch request it shows that the ${env:YOUR_ID} was substituted.

So, can you look at what the situation is on your end? This is my VSC version

Version: 1.105.1 (user setup)
Commit: 7d842fb85a0275a4a8e4d7e040d2625abbf7f084
Date: 2025-10-14T22:33:36.618Z
Electron: 37.6.0
ElectronBuildId: 12502201
Chromium: 138.0.7204.251
Node.js: 22.19.0
V8: 13.8.258.32-electron.0
OS: Windows_NT x64 10.0.26100

[Tolsee]

I got this issue in originally in Cursor. Today, I checked it in VS Code and it is working well like you described. Maybe the fix you didn't landed on Cursor? What do you think about keeping this for any other VS Code clones which might not have latest VS Code?

[zobo]

I'm reluctant to merge this, as this should be fixed by the IDEs... Perhaps try to open an issue with Cursor - they probably do a periodic sync with the main code-base. If ti doesn't work out with them, I'll reconsider merging.