Support no folder debugging

[isidorn]

Hi VS Code PM here 👋

1. Purple no folder VS Code -> create a new php file
2. Press F5 -> notice how we offer the user to download your extension 👏
3. Now the user presses F5 again and wants to debug, but nothing happens since php-debug is not supporting single folder debugging

Easiest to do this is to have a dynamic resolveDebugConfiguartion that will provide a launch configuration on the fly. Example

Apart from that consider contributing to the Editor title area menu, such that a Play button would appear in the Editor Title area (picture below). Example how to do this https://github.com/microsoft/vscode-mock-debug/blob/main/package.json#L80

I think both of these are super important and would really love that we improve this experience 💯
Let me know if I can help somehow. I am also open to a quick 30 min meeting where we can discuss about the new cool VS Code debug features that php-debug could potentially adopt.

fyi @weinand

[zobo]

Hi @isidorn ! Great to hear from you, thanks for reaching out.

I'll have a more in depth look at what you are suggesting here, but I already think there should be no problem providing this. There are a few specifics how PHP debugging works, so I might need to take these into account. One is "listen for connection" the other is "listen and run".

Short meeting sounds great, I'd love to hear what's coming next. I'll try to put together any issues I had with VSC/DAP recently to see if there is anything that is already being addressed.

Let me know how we can schedule, but I would prefer early next week so I have time to prepare.

Thanks!

[isidorn]

@zobo yes some time next week would be great. I just sent you an email, so we work out the timing.

[isidorn]

As we discussed in the meeting, here are some of the cool features that php-debug could adopt. @weinand and @roblourens please jump in with ideas.

No folder debugging as mentioned above

Easiest to do this is to have a dynamic resolveDebugConfiguartion that will provide a launch configuration on the fly.
Example

Contribute to debug start

This should have commands that help user setup and start debugging. Example and more details in this issue microsoft/vscode-cpptools/issues/4837

Contribute to inline value providers

Should allow to have yellow inline values on the side while debugging More details in this issue microsoft/vscode/issues/105690

Contribute the play button in editor title area

Example https://github.com/microsoft/vscode-java-debug/blob/main/package.json#L186

• Java repo which has a lot of this things implemented as an example https://github.com/microsoft/vscode-java-debug
• Opened this issue based on our discussion PHP docs need to be improved microsoft/vscode-docs#4800
• A list of release notes, we always have a section called Debugging so that might be interesting to checkout from time to time https://code.visualstudio.com/updates/v1_59
• Issue for GitHub sponsors which we talked about, feel free to chime in there Explore integration between extensions view and GitHub Sponsors microsoft/vscode#107482

Feel free to ping us for any questions you might have. And thank you very much for improving php debugging 👏 👏

[zobo]

Thanks for all the examples and suggestions. I did a basic implementation for no folder in #645 and will try to further extend it with editor menu contribution.

I will have a look at the other suggestions. I think the "contribute to debug start" is very interesting. Having the extension guide the user through setup would be invaluable. I think this would need to include:

• check if php is in path
• check if it's in some global setting (php.executablePath or php.validate.executablePath?)
• offer the user to set those?
• analyze the php version and possible installed Xdebug version.
• calculate what Xdebug version to download (windows?)
• change the php.ini files
• ...

[isidorn]

@zobo sounds good.

The extension could guide the user through a series of quick picks (if user interaction is needed).

Maybe related to this: if there are different Xdebug versions per platform, and if you want to ship Xdebug as part of the extension - we are currently working on platform specific extensions microsoft/vscode#23251

[AnrDaemon]

check if php is in path
check if it's in some global setting (php.executablePath or php.validate.executablePath?)

What if I simply have configured association? (Windows)
"PHP in PATH" is not a Windows way of doing things.

[zobo]

Hi. Yes, I do agree that on windows (my primary platform also) people tend to avoid putting everything into PATH. However looking up executables for specific filename extensions feels... wrong.

I feel providing a VS Code settings variable is the right way to go, in case we can't find php.exe in the PATH.

@isidorn I believe VS Code already uses php.validate.executablePath setting for it's internal PHP extension. What would be the best setting to enable the user to set the path to their PHP executable? Perhaps add php.executablePath and also check php.validate.executablePath?

I'd use this logic for the no-folder debugging and also extend it to when a launch configuration is provided, but not runtimeExecutable is set by the user.

Thanks!

[AnrDaemon]

I feel providing a VS Code settings variable is the right way to go, in case we can't find php.exe in the PATH.

php.validate.executablePath

Already exists.

[isidorn]

Perhaps add php.executablePath and also check php.validate.executablePath?

This sounds reasonable to me.

[zobo]

Hi @isidorn .

I added editor/title/run to the extension, but noticed that your example from java (https://github.com/microsoft/vscode-java-debug/blob/main/package.json#L186) uses when with resourceExtname, but a lot of other examples I found used languageId.

    "menus": {
      "editor/title/run": [
        {
          "command": "workbench.action.debug.start",
          "when": "resourceLangId == php"
        }
      ]
    },

e9e4b85#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519R432

Any hint on what is better and why?

Also, would it make sense to show the editor/title/run button only when there is no launch.json?

Thanks!

[isidorn]

@zobo sorry for the slow response.
resourceLangId is better because it will also work for Untitled files when the user sets the language mode explicitly to php (and that file might not yet be on disk and thus does not have an extension).
fyi @testforstephen if java would potentially also change to resourceLangId. Or if there are reasons I am missing for using resourceExtname?

I would always show it in editor/title/run. We noticed that it is just convenient for users to click there unrelated if there is a launch.json or not. Though I leave this up to you as to whatever you think is best.

Thanks for working on this 👏

[weinand]

@zobo I'm now back from vacation...

You've asked:

Also, would it make sense to show the editor/title/run button only when there is no launch.json?

No, the editor's run/debug menu is independent ("orthogonal") to the launch.json. This makes it possible to run or debug the editor contents without being affected by anything configured in the launch.json.

I've noticed that you are using the workbench.action.debug.start action in the editor/title/run contribution. This is not a good choice because this action just runs the selected launch config (which can be anything not even related to php).

You must implement and register your own php-specific command in your extension and use that command in the editor/title/run contribution. And the implementation must handle all the possible cases, e.g. "no folder" debugging, no php installed, etc.

Please see how this is done in Mock Debug: https://github.com/microsoft/vscode-mock-debug/blob/6a3df6d2e8bed44408f137d61053b8a8c020523f/src/activateMockDebug.ts#L15-L45

[zobo]

Hi Andre.

Thanks for your input, I was already leaning into this direction as I saw java implemented it like this - I just didn't get around changing it yet.

Since I have you both here, there is another situation I wanted to ask about:
One typical mode of operation for a DBGP client could be described as "read only" mode. Here, the IDE/Client would listen for DBGP connections from PHP, typically from a remote server. When a connection is established all files are downloaded over the DBGP connection on a request basis. All this is already doable within the Debug Adapter Protocol.

So what I'm asking is, what would be the best way to use VS Code as a standalone/no-folder/no-files tool? All this can be configured with launch.json properties, but I think I'd like to have a button or menu item for the user to trigger this feature.

Does this sound familiar to anything somebody else is doing?

Thanks!

[isidorn]

@zobo I am not aware of anyone else doing something like this.

A potential entry point for this would be in the Debug Welcome View, or you could add a Command Palette Entry.
I am not sure where else would this command fit best.

@weinand might have better ideas.

[weinand]

@zobo what you call "read only" mode, sounds similar to VS Code's "JavaScript Debug terminal".

When running a node.js program in the JavaScript Debug terminal, a debug session will be automatically created as soon as the node.js runtime tries to connect to a specific debug port. In order to make the node.js runtime issue a connect request to the debug port, the "JavaScript Debug terminal" just sets a specific environment variable that the node.js runtime picks up.

Since the debug session is initiated by the runtime or debuggee (instead of the user), I would call this mode "reverse mode" (instead of "read only" mode).

you said:

... I think I'd like to have a button or menu item for the user to trigger this feature

Yes, it makes perfect sense to enter this mode not by running a launch config. In the JavaScript case from above, starting the "JavaScript Debug terminal" enters this mode for all programs that are launched from that terminal.

I'm not sure whether it would make sense to use the same approach for "php" because I don't think that "php" is typically launched from the command line.

So maybe your "button" is a better way to control the "reverse mode". Js-debug uses a button in the status bar for controlling the "auto attach" mode. Since the statusbar is always visible this would be a preferable location for a "mode" button.

@connor4312 since you know much more about this "reverse mode", I suggest that you chime in for additional ideas and suggestions.

[zobo]

Yes, I did think about Debug Welcome View and will definitely try that, but I think that is only available when there is no lunch config.
It might be enough in this case, just wondered if there's an option to add it under Run menu or something...

[zobo]

@weinand

I've noticed that you are using the workbench.action.debug.start action in the editor/title/run contribution. This is not a good choice because this action just runs the selected launch config (which can be anything not even related to php).

You must implement and register your own php-specific command in your extension and use that command in the editor/title/run contribution. And the implementation must handle all the possible cases, e.g. "no folder" debugging, no php installed, etc.

I have added a special command php.debug.debugPhpFile

vscode-php-debug/package.json

Line 435 in 462fe24

"command": "php.debug.debugPhpFile",

that just initiates a no-folder debug session

vscode-php-debug/src/extension.ts

Line 63 in 462fe24

vscode.commands.registerCommand('php.debug.debugPhpFile', async (uri: vscode.Uri) => {

. The filter on the menu and command should prevent it being used in any other case - as far as I understand it.

[weinand]

@zobo yes, the contributed "php.debug.debugPhpFile" command will only be visible if the editor's contents is of language type "php"

[zobo]

@zobo yes, the contributed "php.debug.debugPhpFile" command will only be visible if the editor's contents is of language type "php"

Correct, but until I added the condition on the commands part it was always accessible in the palette (Ctrl-P >). Hope I caught all the cases :)

[testforstephen]

if java would potentially also change to resourceLangId. Or if there are reasons I am missing for using resourceExtname?

In Java extension, we use resourceExtname to restrict the "Run" button to appear only on the user's .java source files. Don't want to apply it to the .class files from dependencies. We use custom content provider to open .class file in read-only mode if it has source jar attached.

If php doesn't have similar requirement, resourceLangId would be better.

[isidorn]

Awesome 👏 Thanks for doing this 🎉

[zobo]

Now we just need to wait for GitHub Actions to come back up, so a release can be made available :)