move troubleshooting to the guide and write it

[carlos-granados]

Moves the troubleshooting placeholder from Advanced into the User Guide, as its last page, and writes it. Advanced is left with Performance and Remote Debugging.

Organised as a ladder rather than a symptom list, on the premise that nearly every report is one of three things: it is not running, it cannot reach your editor, or the paths do not match.

1. Is it loaded? — php -v and the line to look for, split by whether you are running the interpreter with the debugger built in (its absence means a different PHP is running) or the extension (look above the version banner for a Failed loading line, and check php --ini).
2. Then ask the debugger — php_debugger_info(), and specifically the Diagnostic Log section it prints, which collects every warning and error raised during the request with no configuration needed.
3. Nothing happens at all — mode, a leftover zend_extension=xdebug.so, start_with_request.
4. It tries to connect but nothing arrives — the log answers it; the two outcomes lead opposite ways.
5. It connects but breakpoints do not fire — path mapping first, then non-executable lines, silently-false conditions, and the file not being the one running.
6. It works, but everything is slow — forgotten breakpoints, on_demand_debugging_enabled.
7. Still stuck — level 10 for "why did it not even try", level 5 for "what was actually sent".

The php -v output and the shape of a failed extension load were both taken from running the images, not from memory.

/advanced/troubleshooting/ will 404. Nothing linked to it and it only ever held placeholder text.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-08 20:17 UTC