PHP 驱动的自定义 IDE 插件开发：利用 LSP 协议在 Cursor/VSCode 中增强 PHP 语义分析

各位开发者，各位“码农”，各位在这个充满 Bug 和咖啡因的世界里寻找存在感的朋友们，大家好。

欢迎来到今天的讲座。我是你们的老朋友，一个热衷于把简单的事情搞复杂，然后把复杂的事情搞懂的人。

今天我们要聊的话题非常硬核，甚至有点“疯癫”。我们不做那些花里胡哨的 UI 组件，不做那些只有 10% 命中率的 AI 聊天机器人。我们要干一件大事：我们要给 PHP 这门语言装上第二颗心脏，给它一颗名为 LSP 的脑细胞。

想象一下，你打开你的 Cursor 或者 VSCode，面对着一行行 PHP 代码。你的 IDE 懂语法，它知道 function 是什么，知道 public 是什么，甚至知道 $this 指向哪里。但是，它不懂你的业务逻辑，不懂你的自定义注解，不懂你那个只有你能看懂的私有变量命名规范。它就像个只会读死书的书呆子，而不是你那个通晓万物的智慧老友。

今天，我们要做的就是——把 PHP 搬到语言服务器的椅子上，让它亲自去分析代码，而不是把代码丢给 IDE 的那个笨脑袋去猜。

准备好了吗？让我们开始这场编程界的“特洛伊木马”行动。

---

第一部分：LSP 是什么？它为什么能拯救你的发际线？

在我们开始写代码之前，必须先来一点“哲学思辨”，虽然我知道你们更喜欢看 var_dump。

传统的 IDE 扩展开发是这样的：你写一个插件，VSCode 或者 Cursor 加载它。然后当你打开一个文件，插件读取这个文件，提取关键词，做正则匹配，然后显示一个提示。这就像是在看图猜成语，拼拼凑凑，错误百出。

而 LSP（Language Server Protocol）是什么？它是微软在 2016 年发明的协议。它是一个标准，就像 HTTP 协议一样，规定了“客户端”（也就是你的 VSCode/Cursor）和“服务器”（也就是你的 PHP 程序）之间该怎么说话。

LSP 的核心思想是：“别把脑子装进 IDE 里了，把脑子装进独立的进程里吧。”

听起来很抽象，对吧？让我打个比方。

想象你的 IDE 是一辆法拉利。PHP 代码就是发动机。
传统的做法是：你把发动机直接塞进法拉利里。这就导致了法拉利变得极其笨重，而且很难维护。你想升级发动机，你得把整辆车拆了。
LSP 的做法是：你把法拉利停在车库里，然后在车库里建一个单独的赛车场。这个赛车场里有一台超级计算机。当你想让车跑起来的时候，你把数据传给这台计算机，计算机算好了，再告诉你怎么开。

这台“超级计算机”就是我们的 Language Server，而我们要写的这个程序，就是这台计算机的 PHP 芯片。

我们要用 PHP 来写这个 Language Server。为什么？因为你们都想在 PHP 的世界里畅游，对吧？用 PHP 去解析 PHP，那是何等的优雅！

---

第二部分：环境搭建——我们要用 PHP 做个“外交官”

要搭建一个 PHP LSP 服务器，我们不能用那种同步阻塞的写法。为什么？因为 IDE 的请求那是成千上万条涌过来的，如果你写一个 sleep(5)，你的服务器就会死机，IDE 就会卡死，用户就会把你卸载，然后你的老板就会问：“为什么代码跑不通？”

我们需要异步。

在我们的工具箱里，有一个神器叫做 AMP (Async Messaging Protocol)，配合 Amphp。它们是 PHP 世界的 Promise 和 Async/Await 之父。

首先，我们需要初始化一个项目。

composer init
composer require amphp/amp amphp/socket amphp/http amphp/dns

当然，我们还需要一个解析器来理解 PHP 的代码结构。纯手写解析器（比如 YY 等）太累了，而且容易出错。我们要用 Nikic 的 PHP Parser。它能让我们把代码变成抽象语法树（AST），这才是“语义分析”的根基。

composer require nikic/php-parser

好了，工具备齐。现在，请拿出你们的键盘，我们要开始编写这个“外交官”的核心代码。

---

第三部分：协议基础——JSON-RPC 的魔咒

LSP 基于标准的 JSON-RPC 2.0 协议。这意味着，我们发出去的消息必须长这样：

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "processId": 12345,
        "rootUri": "file:///path/to/project",
        "capabilities": {
            "textDocument": {
                "completion": {
                    "completionItem": {
                        "snippetSupport": true
                    }
                }
            }
        }
    }
}

收到消息后，我们要回个信：

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "capabilities": {
            "textDocumentSync": 1,
            "completionProvider": {
                "resolveProvider": false
            }
        }
    }
}

这就是外交辞令。我们要写代码来处理这些 JSON 字符串。

在 PHP 中，处理 JSON 我们有 json_decode 和 json_encode。但是，我们需要把它们变成对象，然后根据 method 字段分发到不同的处理器。

这里有一个基础的消息处理器的雏形。为了保持代码在讲座中的可读性，我们忽略错误处理和复杂的流管理，只看核心逻辑。

<?php

use AmpLoop;
use AmpSocket;

// 我们需要一个异步的 socket 服务器
// 默认监听 5173 端口，这是 LSP 的标准端口
$server = Socketlisten('127.0.0.1:5173');

// 这是我们的 LSP 服务器类
class PhpLspServer {
    private $parser;

    public function __construct() {
        // 实例化解析器
        $this->parser = new PhpParserParserFactory()->create(PhpParserParserFactory::PREFER_PHP7);
    }

    // 处理输入流
    public function handleInput(string $jsonInput) {
        // 1. 解码 JSON
        $decoded = json_decode($jsonInput, true);
        if (!$decoded) {
            return null; // 处理解析错误
        }

        // 2. 根据 method 分发
        switch ($decoded['method']) {
            case 'initialize':
                return $this->handleInitialize($decoded);
            case 'textDocument/didOpen':
                return $this->handleTextDocumentOpen($decoded);
            case 'textDocument/didChange':
                return $this->handleTextDocumentChange($decoded);
            case 'textDocument/completion':
                return $this->handleCompletion($decoded);
            default:
                // 忽略不支持的请求
                return null;
        }
    }

    private function handleInitialize($params) {
        return [
            'jsonrpc' => '2.0',
            'id' => $params['id'],
            'result' => [
                'capabilities' => [
                    'textDocumentSync' => 1, // 1 表示全量同步，2 表示增量同步
                    'completionProvider' => [
                        'triggerCharacters' => ['$'],
                        'resolveProvider' => false
                    ],
                    'hoverProvider' => true
                ]
            ]
        ];
    }

    private function handleTextDocumentOpen($params) {
        // 这里可以触发对文件的语义分析
        // 保存当前打开的文档内容
        $uri = $params['params']['textDocument']['uri'];
        $content = $params['params']['textDocument']['text'];

        // 打印日志，证明我们收到了
        echo "[Server] File opened: $urin";
        echo "[Server] Content length: " . strlen($content) . " bytesn";

        // 返回空结果，表示成功
        return [
            'jsonrpc' => '2.0',
            'id' => $params['id'],
            'result' => null
        ];
    }

    private function handleCompletion($params) {
        // 获取光标位置
        $text = $params['params']['textDocument']['text'];
        $position = $params['params']['position'];

        // 这里是我们的魔法时刻
        // 我们要解析 text，找到光标前的那个变量或类
        $snippet = $this->generateCompletionSnippet($text, $position);

        return [
            'jsonrpc' => '2.0',
            'id' => $params['id'],
            'result' => [
                'isIncomplete' => false,
                'items' => [
                    [
                        'label' => 'AwesomeFunction',
                        'kind' => 2, // 2 = Function
                        'detail' => 'This is a custom function parsed by PHP',
                        'insertText' => $snippet
                    ]
                ]
            ]
        ];
    }

    // 这是一个简单的模拟函数，真正的语义分析会使用 AST
    private function generateCompletionSnippet(string $text, array $position) {
        // 实际上，我们需要解析 $this-> 或者 $obj-> 前面的内容
        // 然后查表（数据库、缓存或 AST）
        return 'awesomeFunction($params)';
    }
}

// 启动服务器监听
Loop::run(function () {
    $server = new PhpLspServer();
    echo "LSP Server started on port 5173...n";

    while ($conn = yield $server->accept()) {
        Loop::onReadable($conn->stream, function ($watcherId, $conn) use ($server) {
            $data = yield $conn->read();
            if ($data === null) {
                Loop::cancel($watcherId);
                return;
            }

            // 处理这一批 JSON-RPC 消息
            $messages = explode("nn", trim($data));
            foreach ($messages as $msg) {
                if (empty($msg)) continue;

                $response = $server->handleInput($msg);
                if ($response) {
                    // 发送响应
                    $conn->write(json_encode($response) . "nn");
                }
            }
        });
    }
});

这就是一个最基础的服务器骨架。是不是很简单？只要把 handleInput 写得足够健壮，你就能控制整个 IDE 的生命周期。

---

第四部分：深度解析——当 PHP 遇到 AST

好，我们现在有了骨架。接下来，我们要解决最核心的问题：如何让 PHP 真正读懂 PHP？

我们之前的 generateCompletionSnippet 函数简直是在胡扯。如果我们在代码里写 $user->，IDE 应该知道 $user 是个对象，然后列出它的方法。而不是让我猜。

这就是 AST (Abstract Syntax Tree) 的用武之地。

当 IDE 发送 textDocument/didChange 消息时，我们不仅仅是接收字符串。我们要把这个字符串扔给解析器，把它变成树。

让我们扩展一下 PhpLspServer，加入真正的 AST 解析逻辑。

use PhpParserNode;
use PhpParserNodeVisitorAbstract;
use PhpParserParserFactory;
use PhpParserNodeTraverser;

class CompletionVisitor extends NodeVisitorAbstract {
    private $currentVarName = null;
    private $results = [];

    // 监听变量访问节点 (例如 $this->, $user->)
    public function enterNode(Node $node) {
        if ($node instanceof NodeExprVariable) {
            if (isset($node->name)) {
                $this->currentVarName = $node->name;
            }
        }

        // 监听对象属性访问 (例如 $this->getName())
        if ($node instanceof NodeExprPropertyFetch) {
            if ($node->var instanceof NodeExprVariable) {
                $this->currentVarName = $node->var->name;
            }
        }
    }

    // 监听函数调用 (例如 $user->getName())
    public function leaveNode(Node $node) {
        if ($node instanceof NodeExprMethodCall && $this->currentVarName) {
            // 如果我们在访问一个方法，而当前变量名是 $this 或具体对象名
            // 我们可以在这里生成补全列表
            // 注意：这里仅仅是演示逻辑，真正的类型推断需要更复杂的系统

            if ($this->currentVarName === 'user' || $this->currentVarName === 'this') {
                // 假设我们有一个自定义的数据库或者配置文件知道 user 有哪些方法
                // 在实际生产中，你会解析类定义文件
                $this->results[] = 'getName()';
                $this->results[] = 'setEmail()';
                $this->results[] = 'getOrders()';
            }
        }
    }
}

现在，我们把这个 Visitor 整合到我们的服务器里。

private function handleTextDocumentChange($params) {
    $uri = $params['params']['textDocument']['uri'];
    $content = $params['params']['contentChanges'][0]['text'] ?? ''; // 处理增量更新

    // 1. 创建解析器
    $parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);

    // 2. 创建遍历器
    $traverser = new NodeTraverser();
    $visitor = new CompletionVisitor();
    $traverser->addVisitor($visitor);

    try {
        // 3. 解析代码
        $ast = $parser->parse($content);

        if ($ast) {
            // 4. 遍历 AST
            $traverser->traverse($ast);

            // 将结果缓存，供后续的 completion 请求使用
            $this->cache->set($uri, [
                'variables' => $visitor->getVariables(),
                'methods' => $visitor->getMethods()
            ]);
        }
    } catch (PhpParserError $e) {
        // 忽略语法错误，或者记录下来
    }

    return [
        'jsonrpc' => '2.0',
        'id' => $params['id'],
        'result' => null
    ];
}

现在，如果你在一个文件里写 $user->，你的 PHP 服务器在后台默默解析了整个文件，记下了 $user 这个变量名，然后当你按下 Tab 键时，它就能瞬间告诉你有哪些方法。

这比 IDE 原生的支持要快，而且更精准，因为这是真正的代码运行时的逻辑（虽然我们是在服务器端解析）。

---

第五部分：Diagnostics —— 让你的代码红得像你的眼睛

作为一个资深开发者，我们最痛恨什么？不是 Bug，而是 IDE 不知道这是 Bug。

当我们使用 textDocument/publishDiagnostics 方法时，我们就是在告诉客户端：“嘿，这里有个问题！”

这通常用于静态分析。比如，如果你在一个 try-catch 块里调用了 echo（在某些风格中是禁止的），或者你使用了未定义的变量。

让我们来写一个简单的静态分析规则：禁止在异步代码中使用 sleep()。

在我们的 PHP 服务器里，我们可以监听 textDocument/didChange，解析 AST。如果发现代码中调用了 sleep()，我们就记录下来。

private function analyzeCode($content) {
    $parser = (new ParserFactory)->create(ParserFactory::PREFER_PHP7);
    $traverser = new NodeTraverser();
    $diagnosticVisitor = new class extends NodeVisitorAbstract {
        public $diagnostics = [];

        public function enterNode(Node $node) {
            // 查找函数调用
            if ($node instanceof NodeExprFunctionCall) {
                if ($node->name instanceof NodeIdentifier && $node->name->toString() === 'sleep') {
                    $this->diagnostics[] = [
                        'range' => [
                            'start' => ['line' => $node->getStartLine(), 'character' => $node->getStartTokenPos()],
                            'end' => ['line' => $node->getEndLine(), 'character' => $node->getEndTokenPos()]
                        ],
                        'severity' => 1, // 1 = Error
                        'source' => 'PHP-Super-LSP',
                        'message' => '禁止在异步 LSP 服务器中使用同步阻塞的 sleep()！你会卡死客户端的！'
                    ];
                }
            }
        }
    };

    $traverser->addVisitor($diagnosticVisitor);
    $traverser->traverse($parser->parse($content));

    return $diagnosticVisitor->diagnostics;
}

// 发送诊断结果的函数
private function handleDiagnostics($uri, $diagnostics) {
    $response = [
        'jsonrpc' => '2.0',
        'method' => 'textDocument/publishDiagnostics',
        'params' => [
            'uri' => $uri,
            'diagnostics' => $diagnostics
        ]
    ];

    // 这里你需要发送响应给客户端，通常通过一个全局的响应发送器
    // 为了简化示例，我们假设有一个 $connection 变量
    // $this->broadcast(json_encode($response));
}

当你保存文件时，你的 PHP 服务器会立刻扫描代码，如果发现有 sleep()，它就会给 VSCode 发一条消息。VSCode 看到消息后，会在代码行下方画上一条鲜红色的波浪线，并弹出警告：“嘿，哥们，别用 sleep 了，除非你想让用户以为你的 IDE 炸了。”

这就是“增强语义分析”的魅力。你不仅是在补全代码，你是在审查代码。

---

第六部分：集成与配置 —— 把它塞进 IDE 的胃里

好了，现在你的 PHP 服务器已经写好了，它是一个独立的进程，监听着 5173 端口，正在疯狂地解析代码，吐出智能建议和错误提示。

但是，VSCode 或者 Cursor 不知道这个进程的存在。它们还是像以前一样，傻乎乎地等着你的 PHP 扩展去解析。

你需要告诉它们：“嘿，别用那个内置的 PHP 支持（如果有的话）了，用我这个新来的！”

这主要通过配置文件来实现。通常在你的项目根目录下创建一个 .vscode/settings.json（或者 Cursor 会在项目根目录找配置）。

{
    // 这里的配置告诉 LSP 客户端（VSCode/Cursor）去哪里找你的服务器
    "php.validate.executablePath": null, // 关闭原生的 PHP 验证，因为我们有自己的

    // 这是我们自定义 LSP 的配置
    "lspconfig.php-intelephense-server.enabled": false, // 禁用那些插件的，我们要自己来

    // 如果你使用的是类似 "language-server-php" 的 VSCode 扩展来启动你的服务器，
    // 配置通常是这样的：
    // "php.executablePath": "php", 
    // "php.languageServer.path": "vendor/bin/php-lsp-server"
}

(注：具体的配置方式取决于你使用的启动器，但核心逻辑一致：将 LSP 客户端的配置指向你的 PHP 脚本。)

对于 Cursor，它本质上也是基于 VSCode 的，所以配置逻辑是一样的。它允许你通过 settings.json 或者 .cursorrules 文件来指定使用哪个 LSP 服务器。

---

第七部分：进阶技巧与性能优化

现在，你有一个 PHP 服务器了。但是，你可能会遇到性能问题。

问题 1：文件很多怎么办？
当用户打开一个包含 5000 个文件的 Composer 项目时，如果每个文件都触发一次全量解析，你的 CPU 就会爆表。

解决方案：增量解析。
LSP 协议支持增量更新。当用户只改动了文件的一行时，不要重新解析整个文件。使用 AST 的增量更新功能（PHP Parser 其实也支持部分解析，但这需要更复杂的逻辑），只解析变化的部分。

问题 2：如何处理类型推断？
PHP 是弱类型语言。$user 可能是数组，可能是对象，可能是 null。
如果你在 $user-> 后面想补全，你得知道 $user 是个什么对象。
这时候，你需要结合 Psalm 或 PHPStan 的数据流分析。把它们的分析结果作为你的 LSP 服务器的“数据库”。当用户输入 $user 时，你的 PHP 服务器去查询 PHPStan 的结果，然后决定补全哪些方法。

问题 3：文件系统监控。
你的服务器不应该一直转着圈等待消息。当文件系统发生变化时，你应该主动去解析。
在 Amphp 中，你可以使用 FilesystemFilesystem 来监听文件变化，然后触发解析。

---

结语：做自己代码的主人

写到这里，我相信你们已经对 PHP 驱动的 LSP 服务器有了一个清晰的认识。

我们不再是被动的使用者，我们成为了 IDE 的构建者。我们利用 PHP 强大的生态（Composer, PHP Parser, Amphp），结合现代协议（LSP），构建了一个既懂 PHP 语法，又懂你业务逻辑的智能助手。

当你看到 Cursor 中自动补全的代码完全符合你项目的命名规范，当你看到红色的波浪线精准地标记出那些潜在的 Bug，那种成就感是无可替代的。这不仅仅是技术，这是一种掌控感。

所以，别再满足于默认的 PHP 支持。去写一个自己的 LSP 服务器吧。去定义什么是“好代码”，去定义什么是“智能提示”。

记住，代码是写给机器看的，但 IDE 是写给人看的。我们要做的，就是让 IDE 真正理解人，理解那个正在屏幕前熬夜敲键盘的你。

好了，讲座结束。现在，拿起你的键盘，去创造奇迹吧！如果遇到 Bug，记得重启服务器，通常都能解决 50% 的问题。祝你们好运！