| 1 | # LSP：PHP 内置支持与自定义语言服务器扩展 |
| 2 | |
| 3 | > v0.8.65+ | `codex/lsp-php-custom-servers` |
| 4 | > |
| 5 | > 英文原文：[LSP_PHP_CUSTOM.md](../LSP_PHP_CUSTOM.md)。 |
| 6 | > 最后与英文同步日期（last synced with English revision）：2026-09-29。 |
| 7 | |
| 8 | ## 概述 |
| 9 | |
| 10 | 本次改动将 **PHP** 加入内置 LSP 语言注册表，并新增 `[lsp.custom]` 配置段， |
| 11 | 允许用户按文件扩展名注册任意 LSP 服务器——覆盖内置 `Language` 枚举未包含的 |
| 12 | 语言（Ruby、C#、Swift、Lua 等）。 |
| 13 | |
| 14 | ## 改动内容 |
| 15 | |
| 16 | ### 1. PHP 内置支持 |
| 17 | |
| 18 | - 在 `crates/tui/src/lsp/registry.rs` 的 `Language` 枚举中添加 `Php` 变体 |
| 19 | - `.php` 文件自动检测，默认路由至 `intelephense --stdio` |
| 20 | - 用户可通过 `[lsp.servers].php` 覆盖默认命令 |
| 21 | |
| 22 | ### 2. 自定义 LSP 服务器扩展 |
| 23 | |
| 24 | 新增 `CustomLspDef` 结构体（定义于 `crates/tui/src/lsp/mod.rs`，同步至 |
| 25 | `crates/config/src/lib.rs`）： |
| 26 | |
| 27 | ```rust |
| 28 | pub struct CustomLspDef { |
| 29 | pub language_id: String, // textDocument/didOpen 使用的 LSP languageId |
| 30 | pub command: String, // 要启动的可执行文件 |
| 31 | pub args: Vec<String>, // 参数（默认为空） |
| 32 | } |
| 33 | ``` |
| 34 | |
| 35 | 新增配置字段 `LspConfig.custom: HashMap<String, CustomLspDef>` —— 以文件扩展名 |
| 36 | （不含前导点）为键，如 `"rb"`、`"cs"`、`"swift"`。 |
| 37 | |
| 38 | `LspManager::diagnostics_for` 中，当内置注册表返回 `Language::Other` 时，管理器 |
| 39 | 会先检查用户自定义表再放弃。自定义服务器拥有独立的按需（惰性）启动的 transport 映射和 |
| 40 | 每个扩展名仅一次的缺失告警（避免日志刷屏）。 |
| 41 | |
| 42 | ### 3. Transport 通用化 |
| 43 | |
| 44 | `StdioLspTransport::spawn` 现接受 `&str language_id` 而非 `Language`，内置和 |
| 45 | 自定义服务器共享同一传输实现。`client.rs` 中移除了旧的 `Language` 导入。 |
| 46 | |
| 47 | ### 4. 提取共享轮询管线 |
| 48 | |
| 49 | `poll_diagnostics` 是新提取的私有方法，内置和自定义诊断路径共用，消除了 |
| 50 | 重复的调用/等待/过滤/排序/截断逻辑。 |
| 51 | |
| 52 | ## 配置 |
| 53 | |
| 54 | ### 内置 PHP（若 `intelephense` 在 PATH 中则默认启用） |
| 55 | |
| 56 | ```toml |
| 57 | # 无需配置 —— .php 文件自动检测。 |
| 58 | # 如需覆盖服务器： |
| 59 | [lsp.servers] |
| 60 | php = ["phpactor", "language-server"] |
| 61 | ``` |
| 62 | |
| 63 | ### 自定义语言服务器 |
| 64 | |
| 65 | ```toml |
| 66 | [lsp.custom.rb] |
| 67 | command = "ruby-lsp" |
| 68 | args = ["--stdio"] |
| 69 | language_id = "ruby" |
| 70 | |
| 71 | [lsp.custom.cs] |
| 72 | command = "csharp-ls" |
| 73 | language_id = "csharp" |
| 74 | |
| 75 | [lsp.custom.swift] |
| 76 | command = "sourcekit-lsp" |
| 77 | language_id = "swift" |
| 78 | ``` |
| 79 | |
| 80 | 键为文件扩展名（不含前导点）。`args` 字段默认为空。 |
| 81 | `language_id` 须与 LSP 服务器在 `textDocument/didOpen` 中期望的值匹配。 |
| 82 | |
| 83 | ## 架构 |
| 84 | |
| 85 | ``` |
| 86 | edit_file / write_file / apply_patch 成功 |
| 87 | │ |
| 88 | ▼ |
| 89 | LspManager.diagnostics_for(file) |
| 90 | │ |
| 91 | ├── custom_for_extension(file) ── 命中？──► transport_for_custom(ext, def) |
| 92 | │ │ |
| 93 | ├── detect_language(file) ── Other？──► 返回 None（跳过） |
| 94 | │ |
| 95 | └── transport_for(lang) |
| 96 | │ |
| 97 | ▼ |
| 98 | poll_diagnostics(file, text, transport) |
| 99 | │ |
| 100 | ▼ |
| 101 | DiagnosticBlock → 注入会话的消息流 |
| 102 | ``` |
| 103 | |
| 104 | ## 验证 |
| 105 | |
| 106 | ``` |
| 107 | cargo test -p codewhale-tui --lib lsp:: |
| 108 | # 32 个测试通过（新增 3 个：detects_php_extension、language_ids_for_php、 |
| 109 | # server_for_php_is_intelephense） |
| 110 | cargo clippy -p codewhale-tui --lib |
| 111 | # lsp 模块：零新增警告 |
| 112 | ``` |
| 113 | |
| 114 | ## 涉及文件 |
| 115 | |
| 116 | | 文件 | 改动 | |
| 117 | |------|------| |
| 118 | | `crates/tui/src/lsp/registry.rs` | +Php 变体、检测、服务器映射、测试 | |
| 119 | | `crates/tui/src/lsp/mod.rs` | +CustomLspDef、LspConfig.custom、LspManager 自定义回退 | |
| 120 | | `crates/tui/src/lsp/client.rs` | spawn 接受 &str language_id | |
| 121 | | `crates/tui/src/config.rs` | LspConfigToml.custom + into_runtime | |
| 122 | | `crates/config/src/lib.rs` | LspConfigToml.custom + CustomLspDef | |
| 123 | | `config.example.toml` | PHP 文档 + 自定义扩展示例 | |
| 124 |