[Feature Request]: Update documentation for xdebug 3

[cprn]

Is your feature request related to a problem? Please describe.
I cannot manage to run Vimspector with Xdebug3, it runs PHP without stopping on breakpoints, displays correct output and shows Protocol error: Server returned no threads each time. I went through documentation back and forth and failed to notice whatever I'm missing. Google doesn't find working examples either.

Describe the solution you'd like
I'd like a working example in documentation.

Describe alternatives you've considered
I tried with several combinations of Xdebug settings but didn't manage to find a working one.

Additional context
Versions:

$ php --version                                                                                                                                                                
PHP 8.1.2 (cli) (built: Jan 24 2022 10:42:51) (NTS)
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Xdebug v3.1.2, Copyright (c) 2002-2021, by Derick Rethans

Vimspector installed with vim-plug without issues.

test.php - file to run vscode-php-debug on:

<?php

echo 'foo';
echo 'bar';    # put breakpoint here with <f9> then start with <f5>
echo 'foobar';

.vimspector.json:

{
    "configurations": {
        "Listen for XDebug": {
            "adapter": "vscode-php-debug",
            "filetypes": [
                "php"
            ],
            "configuration": {
                "name": "Listen for XDebug",
                "type": "php",
                "request": "launch",
                "port": 9003,
                "stopOnEntry": false,
                "pathMappings": {
                    "/var/www/html": "${workspaceRoot}"
                }
            }
        },
        "Launch currently open script": {
            "adapter": "vscode-php-debug",
            "filetypes": [
                "php"
            ],
            "configuration": {
                "name": "Launch currently open script",
                "type": "php",
                "request": "launch",
                "program": "${file}",
                "cwd": "${fileDirname}",
                "port": 9003
            }
        }
    }
}

xdebug.ini:

zend_extension = xdebug.so
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.idekey = xdebug

Vimspector log:

2022-03-02 16:29:48,511 - INFO - **** INITIALISING NEW VIMSPECTOR SESSION ****
2022-03-02 16:29:48,512 - INFO - API is: neo
2022-03-02 16:29:48,512 - INFO - VIMSPECTOR_HOME = /home/mg/.vim/plugged/vimspector
2022-03-02 16:29:48,512 - INFO - gadgetDir = /home/mg/.vim/plugged/vimspector/gadgets/linux
2022-03-02 16:29:51,642 - INFO - User requested start debug session with {}
2022-03-02 16:29:51,644 - DEBUG - Reading configurations from: None
2022-03-02 16:29:51,644 - DEBUG - Reading configurations from: /home/mg/.vimspector.json
2022-03-02 16:29:51,648 - DEBUG - Reading gadget config: /home/mg/.vim/plugged/vimspector/gadgets/linux/.gadgets.json
2022-03-02 16:29:51,648 - DEBUG - Reading gadget config: None
2022-03-02 16:29:53,135 - INFO - Configuration: {"adapter": "vscode-php-debug", "filetypes": ["php"], "configuration": {"name": "Launch currently open script", "type": "php", "request": "launch", "program": "/home/mg/test.php", "cwd": "/home/mg", "port": 9003}}
2022-03-02 16:29:53,135 - INFO - Adapter: {"command": ["node", "/home/mg/.vim/plugged/vimspector/gadgets/linux/vscode-php-debug/out/phpDebug.js"], "name": "php-debug"}
2022-03-02 16:29:53,150 - DEBUG - min_width/height: 149/50, actual: 191/51 - result: horizontal
2022-03-02 16:29:53,395 - DEBUG - LAUNCH!
2022-03-02 16:29:53,396 - INFO - Starting debug adapter with: {"command": ["node", "/home/mg/.vim/plugged/vimspector/gadgets/linux/vscode-php-debug/out/phpDebug.js"], "name": "php-debug"}
2022-03-02 16:29:53,396 - DEBUG - Connection Type: neojob
2022-03-02 16:29:53,398 - INFO - Debug Adapter Started
2022-03-02 16:29:53,398 - DEBUG - Sending Message: {"command": "initialize", "arguments": {"adapterID": "php-debug", "clientID": "vimspector", "clientName": "vimspector", "linesStartAt1": true, "columnsStartAt1": true, "locale": "en_GB", "pathFormat": "path", "supportsVariableType": true, "supportsVariablePaging": false, "supportsRunInTerminalRequest": true, "supportsMemoryReferences": true}, "seq": 0, "type": "request"}
2022-03-02 16:29:53,492 - DEBUG - Message received: {'seq': 1, 'type': 'response', 'request_seq': 0, 'command': 'initialize', 'success': True, 'body': {'supportsConfigurationDoneRequest': True, 'supportsEvaluateForHovers': True, 'supportsConditionalBreakpoints': True, 'supportsFunctionBreakpoints': True, 'supportsLogPoints': True, 'supportsHitConditionalBreakpoints': True, 'supportsSetVariable': True, 'exceptionBreakpointFilters': [{'filter': 'Notice', 'label': 'Notices'}, {'filter': 'Warning', 'label': 'Warnings'}, {'filter': 'Error', 'label': 'Errors'}, {'filter': 'Exception', 'label': 'Exceptions'}, {'filter': '*', 'label': 'Everything'}], 'supportTerminateDebuggee': True}}
2022-03-02 16:29:53,493 - DEBUG - Sending Message: {"command": "launch", "arguments": {"name": "Launch currently open script", "type": "php", "request": "launch", "program": "/home/mg/test.php", "cwd": "/home/mg", "port": 9003}, "seq": 1, "type": "request"}
2022-03-02 16:29:53,511 - DEBUG - Message received: {'seq': 2, 'type': 'response', 'request_seq': 1, 'command': 'launch', 'success': True}
2022-03-02 16:29:53,511 - DEBUG - Message received: {'seq': 3, 'type': 'event', 'event': 'initialized'}
2022-03-02 16:30:01,427 - DEBUG - Sending Message: {"command": "setBreakpoints", "arguments": {"source": {"name": "test.php", "path": "/home/mg/test.php"}, "breakpoints": [{"line": 4}], "sourceModified": false}, "seq": 2, "type": "request"}
2022-03-02 16:30:01,429 - DEBUG - Sending Message: {"command": "setFunctionBreakpoints", "arguments": {"breakpoints": []}, "seq": 3, "type": "request"}
2022-03-02 16:30:01,430 - DEBUG - Sending Message: {"command": "setExceptionBreakpoints", "arguments": {"filters": ["Notice", "Warning", "Error", "Exception", "*"]}, "seq": 4, "type": "request"}
2022-03-02 16:30:01,432 - DEBUG - Message received: {'seq': 4, 'type': 'event', 'event': 'output', 'body': {'category': 'stdout', 'output': 'foobarfoobar'}}
2022-03-02 16:30:01,436 - DEBUG - Message received: {'seq': 5, 'type': 'event', 'event': 'terminated'}
2022-03-02 16:30:01,438 - DEBUG - Message received: {'seq': 6, 'type': 'response', 'request_seq': 2, 'command': 'setBreakpoints', 'success': True, 'body': {'breakpoints': [{'verified': True, 'line': 4, 'source': {'name': 'test.php', 'path': '/home/mg/test.php'}, 'id': 1}]}}
2022-03-02 16:30:01,438 - DEBUG - Breakpoints at this point: {
  "/home/mg/test.php": [
    {
      "verified": true,
      "line": 4,
      "source": {
        "name": "test.php",
        "path": "/home/mg/test.php"
      },
      "id": 1
    }
  ]
}
2022-03-02 16:30:01,438 - DEBUG - Message received: {'seq': 7, 'type': 'response', 'request_seq': 3, 'command': 'setFunctionBreakpoints', 'success': True, 'body': {'breakpoints': []}}
2022-03-02 16:30:01,438 - DEBUG - Breakpoints at this point: {
  "/home/mg/test.php": [
    {
      "verified": true,
      "line": 4,
      "source": {
        "name": "test.php",
        "path": "/home/mg/test.php"
      },
      "id": 1
    }
  ]
}
2022-03-02 16:30:01,439 - DEBUG - Message received: {'seq': 8, 'type': 'response', 'request_seq': 4, 'command': 'setExceptionBreakpoints', 'success': True, 'body': {'breakpoints': [{'verified': True, 'id': 2}, {'verified': True, 'id': 3}, {'verified': True, 'id': 4}, {'verified': True, 'id': 5}, {'verified': True, 'id': 6}]}}
2022-03-02 16:30:01,439 - DEBUG - Sending Message: {"command": "configurationDone", "seq": 5, "type": "request"}
2022-03-02 16:30:01,440 - DEBUG - Message received: {'seq': 9, 'type': 'response', 'request_seq': 5, 'command': 'configurationDone', 'success': True}
2022-03-02 16:30:01,441 - DEBUG - Sending Message: {"command": "threads", "seq": 6, "type": "request"}
2022-03-02 16:30:01,441 - DEBUG - Message received: {'seq': 10, 'type': 'response', 'request_seq': 6, 'command': 'threads', 'success': True, 'body': {'threads': []}}
2022-03-02 16:30:01,441 - INFO - User Msg: Protocol error: Server returned no threads

Screenshot:

[puremourning]

This amounts to a support request, not a feature request, so closing.

[puremourning]

I'd like a working example in documentation.

I'm confident the example in the docs works because I've used it myself. I did however spend some time reading the xdebug and php-debug-adapter docs, as it does seem a nontrivial debug adapter, and quite unusual. @przepompownia can you confirm?

@cprn my recollection is that you need the chrome plugin (or something) to set some cooke that makes the xdebug thing actually break then refresh the page. If I remember correctly, The error about no threads is a common bug in many debug adapters, but is usually harmless.

This is the exact configuration that I have used, and works in my environment. Your configuration may need to be different and you may have to read the docs of the third-party aspects here. Vimspector is not ever going to document third-party things like the debug adapters, and how to make them work, because I am just 1 guy in my spare time and there are literally hundreds of them, and thousands of users.

[cprn]

Example provided by you is for version 2.x of Xdebug. Current version is 3.1. There were changes in major versions that aren't backwards compatible. I tried to follow the migration guide but it didn't help. I'm trying to make it work for about 3 months now on multiple machines. I'm pretty sure the example from documentation only works with Xdebug2.

I don't think I need any browser plugins when running PHP process in CLI (as far as I can tell this config just runs php test.php when I select "Launch currently open script" option). I tried similar configuration with vdebug (Vimspector equivalent dedicated for xdebug) and it works without issues so I expect my problem to be in .vimspector.json or xdebug.ini or in vscode-php-debug itself. I'll look in the adapter repository as well in few hours when I get home.

This amounts to a support request, not a feature request, so closing.

Should I ask on one of the chats listed in the new issue form?

[puremourning]

Well it took me all of 5 minutes to make it work by following the xdebug installation instructions, and then the vscode-php-debug instructions.

• pecl install xdebug

• 99-xdebug.ini:

ben@BeniMac2020 php % cat /usr/local/etc/php/8.1/conf.d/99-xdebug.ini
zend_extension="xdebug.so"
xdebug.mode = debug
xdebug.start_with_request = yes

• php -v

ben@BeniMac2020 php % php -v
PHP 8.1.2 (cli) (built: Feb  3 2022 10:33:53) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Xdebug v3.1.3, Copyright (c) 2002-2022, by Derick Rethans
    with Zend OPcache v8.1.2, Copyright (c), by Zend Technologies

• .vimspector.json

ben@BeniMac2020 php % cat .vimspector.json
{
  "configurations": {
    "Run current scipt": {
      "adapter": "vscode-php-debug",
      "configuration": {
        "request": "launch",
        "program": "${file}",
        "args": [],
        "stopOnEntry": false
      }
    }
  }
}

• test.php

ben@BeniMac2020 php % cat test.php
<?php

$x = 1;
$y = 2;

xdebug_info();

$z = 2;
$z = 2;

?>

Proof: https://asciinema.org/a/A6a8Nbdwzff4W0qNI9BAjvLo2

[cprn]

OK, this I did not expect. It doesn't work with Xdebug installed from repository but works when it's installed from PECL. I'll investigate further but it seems it should be solved by the package maintainer. Thank you for your help. I wasted so many nights. 🤦‍♂️

[puremourning]

you're welcome. for the record I have no clue what pecl is, I just did what the instructions told me to!

[przepompownia]

@puremourning Indeed, it would be good to show some minimal XDebug 3 configuration too, e.g.

xdebug.show_local_vars=on
xdebug.discover_client_host = false
; override with XDEBUG_CONFIG="client_host=192.168.42.34 client_port=9004"
xdebug.client_host = localhost
xdebug.client_port = 9003
xdebug.log=/tmp/xdebug.log
xdebug.mode=debug
xdebug.start_with_request=trigger

@cprn to eliminate the adapter (vscode-php-debug) and the client possible issues, you can try to use CLI DBGP client with xdebug_break(); inside the code (e.g. dbgpClient -x -p 9003).

I did however spend some time reading the xdebug and php-debug-adapter docs, as it does seem a nontrivial debug adapter, and quite unusual. @przepompownia can you confirm?

It's hard to say, given XDebug as the only point of reference 😉