From 3ec30fff3fc9ea89464ec063200b360cec531056 Mon Sep 17 00:00:00 2001
From: Vadim Lazuk <vadim.lazuk@mail.ru>
Date: Fri, 6 Nov 2026 01:27:57 +0300
Subject: [PATCH] fix(debugger): offer to install php-debug when it is missing
 (#1633)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

php-debug had no entry in the missing-adapter table, so a PHP debug session without it failed with a plain error pointing at mason.nvim. It now offers Install and Debug like debugpy, Delve or js-debug, and the hint points to Settings › Languages & Frameworks › Language Servers.

Co-authored-by: Inf1mum <8135225+Inf1mum@users.noreply.github.com>
---
 languages/php.toml                                    |  2 +-
 .../debugger/__tests__/missingAdapter.test.ts         | 11 +++++++++++
 src/features/debugger/missingAdapter.ts               |  1 +
 src/platform/locales/text/zh.json                     |  1 +
 4 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/languages/php.toml b/languages/php.toml
index b0fc0f4e..e3dcf927 100644
--- a/languages/php.toml
+++ b/languages/php.toml
@@ -29,4 +29,4 @@ install-hint = "Install phpactor (https://phpactor.readthedocs.io/en/master/usag
 [debugger]
 adapter = "php-debug"
 command = "php-debug-adapter"
-install-hint = "Install vscode-php-debug (Xdebug) as `php-debug-adapter` (e.g. via mason.nvim) and enable Xdebug"
+install-hint = "Install PHP Debug (Xdebug) in Settings › Languages & Frameworks › Language Servers, and enable Xdebug"
diff --git a/src/features/debugger/__tests__/missingAdapter.test.ts b/src/features/debugger/__tests__/missingAdapter.test.ts
index feb17d38..f791778f 100644
--- a/src/features/debugger/__tests__/missingAdapter.test.ts
+++ b/src/features/debugger/__tests__/missingAdapter.test.ts
@@ -27,6 +27,17 @@ describe("missing debug adapters", () => {
     expect(missingAdapter("delve", unavailable("debug adapter `delve` not found (x)"))?.tool).toBe("delve");
   });
 
+  it("offers the managed install of the missing php-debug adapter", () => {
+    const e = unavailable(
+      "debug adapter `php-debug` not found (`php-debug-adapter` is neither installed by OpenIDEA nor on PATH). Install PHP Debug (Xdebug) in Settings › Languages & Frameworks › Language Servers, and enable Xdebug",
+    );
+    expect(missingAdapter("php-debug", e)).toMatchObject({
+      tool: "php-debug",
+      title: "PHP Debug (Xdebug) is not installed",
+      body: e.message,
+    });
+  });
+
   it("leaves other failures and adapters without an installer alone", () => {
     expect(missingAdapter("js-debug", unavailable("connection refused"))).toBeNull();
     expect(missingAdapter("js-debug", new Error("debug adapter `js-debug` not found"))).toBeNull();
diff --git a/src/features/debugger/missingAdapter.ts b/src/features/debugger/missingAdapter.ts
index dabfb402..357b10b9 100644
--- a/src/features/debugger/missingAdapter.ts
+++ b/src/features/debugger/missingAdapter.ts
@@ -12,6 +12,7 @@ const INSTALLABLE: Record<string, { tool: string; title: string }> = {
   "js-debug": { tool: "js-debug", title: "The JavaScript debugger (vscode-js-debug) is not installed" },
   delve: { tool: "delve", title: "Delve is not installed" },
   codelldb: { tool: "codelldb", title: "CodeLLDB is not installed" },
+  "php-debug": { tool: "php-debug", title: "PHP Debug (Xdebug) is not installed" },
 };
 
 export interface MissingAdapter {
diff --git a/src/platform/locales/text/zh.json b/src/platform/locales/text/zh.json
index 80a549de..50a54d8b 100644
--- a/src/platform/locales/text/zh.json
+++ b/src/platform/locales/text/zh.json
@@ -4123,6 +4123,7 @@
   "The JavaScript debugger (vscode-js-debug) is not installed": "JavaScript 调试器 (vscode-js-debug) 未安装",
   "Delve is not installed": "Delve 未安装",
   "CodeLLDB is not installed": "CodeLLDB 未安装",
+  "PHP Debug (Xdebug) is not installed": "PHP Debug (Xdebug) 未安装",
   "{name} (child)": "{name}（子进程）",
   "Enable breakpoint at {path}:{line}": "启用位于 {path}:{line} 的断点",
   "Headers ({count})": "标头 ({count})",