Setting up debugging with Xdebug and vscode-php-debug

[paulvandermeijs]

Hello, I found this article about setting up Xdebug in Neovim using DAP and vscode-php-debug.

I've tried to do something similar in Helix. So far I've been able to set up a debugger template to start the debug adapter but it crashes Helix on breakpoints with the message below:

thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', /Users/paulvandermeijs/Workspace/helix/helix-view/src/handlers/dap.rs:231:57
stack backtrace:
   0: _rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::panicking::panic
   3: helix_view::handlers::dap::<impl helix_view::editor::Editor>::handle_debugger_message::{{closure}}
   4: helix_term::application::Application::run::{{closure}}
   5: <core::future::from_generator::GenFuture<T> as core::future::future::Future>::poll
   6: tokio::runtime::park::CachedParkThread::block_on
   7: tokio::runtime::scheduler::multi_thread::MultiThread::block_on
   8: tokio::runtime::runtime::Runtime::block_on
   9: hx::main

I'm not sure if this is because I'm still figuring out how to configure the debugger or because debugging is still experimental. Has anyone else got experience with this?

I've used the configuration below in languages.toml to set up the debugger template:

[[language]]
name = "php"

[language.debugger]
name = "vscode-php-debug"
transport = "tcp"
command = "node"
args = [ "<path to phpDebug.js>" ]
port-arg = "--server={}"

[[language.debugger.templates]]
name = "Listen for Xdebug"
request = "launch"
completion = [ "ignored" ]
args = {  }

[eric-hansen]

Have you ever resolved this?

I also wonder if you provided the right args to the phpDebug.js config.

[paulvandermeijs]

No, I haven't. My knowledge about either vscode-php-debug or setting up DAP in Helix doesn't go that far so I'd need to further look into it. I was actually hoping to find someone here that could point me in the right direction since I've been using Helix as my main editor for quite a while but the only thing that keeps me switching back to VS Code is to use Xdebug.

[mattriverm]

Try this. Make sure xdebug is connecting on port 9003.

[language.debugger]
name = "vscode-php-debug"
transport = "stdio"
command = "node"
args = ["/Users/me/.vscode/extensions/xdebug.php-debug-1.33.0/out/phpDebug.js"]

[[language.debugger.templates]]
name = "Listen for Xdebug"
request = "launch"
completion = ["ignored"]
args = {serverSourceRoot="/path/in/container",localSourceRoot="/path/on/host"}

[paulvandermeijs]

Yes, that's it! Thank you so much!

I knew that at some point I had to set up path mappings but didn't figure from the error that this was the issue.

The only thing left is that I've put ignored in the completion array because I couldn't leave it empty but that is just a minor issue.

[chartjes]

I am seeing the same problem in my setup but I am not sure that to put in for serverSourceRoot and localSourceRoot because I am not running things inside a container but debugging code that I am running tests on. I am using a similar configuration to what @mattriverm suggested.

[[language]]
name = "php"
auto-format = true

[language.debugger]
name = "vscode-php-debug"
transport = "stdio"
command = "node"
args = ["/Users/chartjes/vscode-php-debug/out/phpDebug.js"]

[[language.debugger.templates]]
name = "Listen for Xdebug"
request = "launch"
completion = ["ignored"]
args = {serverSourceRoot="/Users/chartjes/ibl.dev/webreg/",localSourceRoot="/Users/chartjes/ibl.dev/webreg/"}

[chartjes]

I will try it in VSCodium. Here is the output for hx --health php

Configured language servers:
  ✓ intelephense: /opt/homebrew/bin/intelephense
Configured debug adapter: node
Binary for debug adapter: /opt/homebrew/bin/node
Highlight queries: ✓
Textobject queries: ✓
Indent queries: ✓

[eric-hansen]

Cool so it does recognize the debugger. :) I'd also check ~/.cache/helix/helix.log (not sure the path in Mac as I use Linux but gonna assume the same).

[chartjes]

Nothing in the log files that relates to debugging

[chartjes]

It also works just fine in VSCodium

[eric-hansen]

Sorry I didn't get to this yesterday. I tested it now and I'm able to get this to work just fine. So I'll break this down to see if maybe a step was missed somewhere. Also, keep in mind I use NixOS so my paths will be different than yours but it doesn't play any part in the functionality.

1. From CLI run node /Users/chartjes/vscode-php-debug/out/phpDebug.js to see if it works or if there are errors. I imagine it will be successful as Codium debugs fine. It should just "hang", waiting for input, which is expected.
2. Have this in your .helix/languages.toml (changing paths as needed) file:

[[language]]
name = "php"
auto-format = true

[language.debugger]
name = "vscode-php-debug"
transport = "stdio"
command = "node"
args = ["/home/eric/.vscode-oss/extensions/xdebug.php-debug-1.34.0-universal/out/phpDebug.js"]

[[language.debugger.templates]]
name = "Listen for XDebug"
request = "launch"
completion = ["ignored"]
args = {}

Note too that the args for the template can have the source/local mapping, it'll work just fine either way, but I would leave them out if you're not using containers for PHP.
3. Create a simple PHP script, I created one that just simply has

<?php
echo("hi");

The rest of the steps will assume the same and default keymappings.
4. Run hx <script file>
5. On the "echo..." line, do <space> g b to toggle the breakpoint (you can toggle after the debugger starts too)
6. The debug menu should still be open, so choose l (lowercase L) to select a debug target
7. You should only have one option here, "Listen for XDebug", so choose that
8. A prompt in the command bar should show up "ignored: ", just hit enter
9. You should see a filled-in red circle next to the line you put the breakpoint on
10. In another terminal, run the script (php <script file>)
11. The breakpoint line now should be highlighted and the script should be paused in the terminal, as well as as "Thread stopped because of breakpoint" message in Helix
12. Continue using the debug menu keys to step through or whatnot

If the above doesn't work for you then I would make sure your XDebug config is in debug mode (assuming v3).

Here's what my php -i shows for xdebug that's relevant:

$ php -i | grep xdebug | grep -v removed | grep -v renamed
xdebug.client_host => localhost => localhost
xdebug.client_port => 9003 => 9003
xdebug.collect_assignments => Off => Off
xdebug.collect_params => On => On
xdebug.collect_return => Off => Off
xdebug.connect_timeout_ms => 200 => 200
xdebug.discover_client_host => Off => Off
xdebug.idekey => vscode => vscode
xdebug.mode => debug => debug
xdebug.start_upon_error => default => default
xdebug.start_with_request => yes => yes

[chartjes]

Still having the same issue and debugging works okay both in NeoVim and PhpStorm. I appreciate all the help but I have sunk enough time into this for now.

[acidindustries]

DAP crashes as soon as the breakpoint is hit with the container config. With serverSourceRoot and localSourceRoot being deprecated, would it be possible to configure the pathMappings variable in languages.toml? How would one go about doing it considering the setting expects a table with a path as the key?

[mattriverm]

It is crashing due to this issue, so right now I think it is unrelated to pathMappings. I don't really see how pathMappings could be specified in the languages.toml because it looks like the config types in helix does not support it.

[acidindustries]

Confirmed. Built helix from source and the issue is fixed. Debugging inside a container is possible with the configuration provided by @mattriverm here