The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
fix(php): document language constructs and clarify rename failures (#354)
l0ng-aib2c183dbd4e5
diff --git a/src/editor/lsp/completion.test.ts b/src/editor/lsp/completion.test.tsindex 83f537c37..e75cf69b0 100644--- a/src/editor/lsp/completion.test.ts+++ b/src/editor/lsp/completion.test.ts@@ -56,6 +56,27 @@ function item(over: Partial<CompletionItem> = {}): CompletionItem {};}+describe("PHP construct completion documentation", () => {+ const req = { doc: 1, path: "/p/a.php", language: "PHP", pos: 3, text: EditorState.create({ doc: "emp" }).doc };++ it("documents a keyword without changing its insertion", () => {+ const c = makeCompletion(item({ label: "empty", kind: "keyword", insertText: "empty" }), req);+ expect(c.lsp.documentation?.value).toContain("empty(mixed $var): bool");+ expect(c.lsp.insertText).toBe("empty");+ });++ it("preserves server documentation and leaves methods and other languages alone", () => {+ const documentation = { kind: "markdown" as const, value: "Server documentation" };+ expect(makeCompletion(item({ label: "empty", kind: "keyword", documentation }), req).lsp.documentation).toEqual(+ documentation,+ );+ expect(makeCompletion(item({ label: "empty", kind: "method" }), req).lsp.documentation).toBeNull();+ expect(+ makeCompletion(item({ label: "empty", kind: "keyword" }), { ...req, language: "JavaScript" }).lsp.documentation,+ ).toBeNull();+ });+});+describe("toCmCompletion", () => {it("maps label, detail, kind and sort text", () => {const c = toCmCompletion(diff --git a/src/editor/lsp/completion.ts b/src/editor/lsp/completion.tsindex 7a9bf7cae..4cbb7543c 100644--- a/src/editor/lsp/completion.ts+++ b/src/editor/lsp/completion.ts@@ -56,6 +56,7 @@ import { editorPrefs } from "@/platform/editorSettings";import { tx } from "@/platform/i18n";import { showHint } from "./hint";import { inplaceRenameActive } from "./inplaceRename";+import { phpConstructDocumentation } from "./phpConstructs";interface RequestContext {doc: number;@@ -87,6 +88,8 @@ function resolveItem(doc: number, item: CompletionItem): Promise<CompletionItem>if (!p) {p = lspRequest(() => commands.lspResolveCompletion(doc, item)).then((r) => {+ if (isEmptyMarkup(r.documentation) && !isEmptyMarkup(item.documentation))+ r = { ...r, documentation: item.documentation };resolvedItems.set(item, r);return r;},@@ -365,6 +368,10 @@ async function fallback(ctx: CompletionContext): Promise<CompletionResult | null}export function makeCompletion(item: CompletionItem, req: RequestContext): LspCompletion {+ if (item.kind === "keyword" && isEmptyMarkup(item.documentation)) {+ const value = phpConstructDocumentation(req.language, item.label);+ if (value) item = { ...item, documentation: { kind: "markdown", value } };+ }// The lookup handles commit characters itself (focused lookups only, see `lookupKeys`).const { commitCharacters: _server, ...cm } = toCmCompletion(item);return Object.assign(cm, {diff --git a/src/editor/lsp/hover.ts b/src/editor/lsp/hover.tsindex fefbdf97a..e6614dc28 100644--- a/src/editor/lsp/hover.ts+++ b/src/editor/lsp/hover.ts@@ -35,6 +35,7 @@ import { applyCodeAction, quickFixesAt } from "./intentions";import { editorPrefs } from "@/platform/editorSettings";import { CONTRIBUTED_HOVER, contributedAt, type ContributedHover } from "@/editor/api";import { navigationModifierHeld, onNavigationModifier, pointerTarget } from "@/platform/navigationModifier";+import { phpConstructAt } from "./phpConstructs";let hoverRequest: RequestId | null = null;@@ -48,6 +49,12 @@ export async function requestHover(view: EditorView, pos: number): Promise<Hover}const doc = docOf(view);if (!doc) return null;+ const construct = phpConstructAt(view.state, pos, doc.language);+ if (construct)+ return {+ contents: { kind: "markdown", value: construct.markdown },+ range: { start: offsetToPos(view.state.doc, construct.from), end: offsetToPos(view.state.doc, construct.to) },+ };if (hoverRequest !== null && isTauri()) void commands.cancelRequest(hoverRequest);const id = (hoverRequest = nextRequestId());try {@@ -230,6 +237,13 @@ function showDoc(view: EditorView, entry: DocEntry, at: number) {});}+export function showPhpConstructDocumentation(view: EditorView, pos: number): boolean {+ const construct = phpConstructAt(view.state, pos, docOf(view)?.language ?? null);+ if (!construct) return false;+ showDoc(view, { markup: { kind: "markdown", value: construct.markdown }, language: "PHP" }, construct.from);+ return true;+}+/*** F1: documentation for the symbol at the caret in a popup (or the* Documentation tool window while it is open); in an open lookup, for its@@ -263,7 +277,10 @@ export async function quickDocumentation(view: EditorView) {{markup: hover.contents,language: ctx?.uiMode ?? null,- source: ctx ? definitionOf(ctx.doc, offsetToPos(view.state.doc, pos)) : undefined,+ source:+ ctx && !phpConstructAt(view.state, pos, ctx.language)+ ? definitionOf(ctx.doc, offsetToPos(view.state.doc, pos))+ : undefined,},hover.range ? rangeToOffsets(view.state.doc, hover.range).from : pos,);@@ -327,6 +344,7 @@ export async function quickDefinition(view: EditorView, kind: "definition" | "tyconst doc = docOf(view);if (!doc) return;const pos = view.state.selection.main.head;+ if (kind === "definition" && showPhpConstructDocumentation(view, pos)) return;try {const found = await lspRequest(() => commands.lspGoto(doc.doc, offsetToPos(view.state.doc, pos), kind));const seen = new Set<string>();diff --git a/src/editor/lsp/navigation.ts b/src/editor/lsp/navigation.tsindex 33052b67b..ca7b84ad7 100644--- a/src/editor/lsp/navigation.ts+++ b/src/editor/lsp/navigation.ts@@ -51,7 +51,7 @@ import { caretAnchor, openPopup, type ListPopupItem } from "./popupStore";import { identifierAt, readManyFileLines } from "./files";import { documentLinks, followReference, knownLinks, linkReference, referenceAt, textReference } from "./links";import { featureBackoff } from "./availability";-import { requestHover } from "./hover";+import { requestHover, showPhpConstructDocumentation } from "./hover";import { declarationSummary, renderCode } from "./markdown";import { editorPrefs } from "@/platform/editorSettings";import { isVirtualUri, virtualContainer } from "@/platform/virtualDocs";@@ -157,6 +157,7 @@ export async function gotoTargets(view: EditorView, kind: GotoKind, at?: number)if (kind === "definition" || kind === "declaration") {const own = contributedAt<ContributedDefinition>(view.state, CONTRIBUTED_DEFINITION, offset);if (own?.(view, offset)) return;+ if (showPhpConstructDocumentation(view, offset)) return;}const doc = docOf(view);if (!doc) return;diff --git a/src/editor/lsp/phpConstructs.test.ts b/src/editor/lsp/phpConstructs.test.tsnew file mode 100644index 000000000..a51aa6b0b--- /dev/null+++ b/src/editor/lsp/phpConstructs.test.ts@@ -0,0 +1,77 @@+import { afterEach, describe, expect, it } from "vitest";+import { EditorState } from "@codemirror/state";+import { EditorView } from "@codemirror/view";+import { languages } from "@codemirror/language-data";+import { phpConstructAt, phpConstructDocumentation } from "./phpConstructs";+import { lspDoc } from "./lsp";+import { quickDefinition, requestHover } from "./hover";+import { gotoTargets } from "./navigation";+import { closePopup, useLspPopup } from "./popupStore";++const php = await languages.find((l) => l.name === "PHP")!.load();+const views: EditorView[] = [];+afterEach(() => {+ closePopup();+ for (const view of views.splice(0)) view.destroy();+});++function state(doc: string) {+ return EditorState.create({ doc, extensions: [php] });+}++describe("PHP language constructs", () => {+ it.each(["empty", "isset", "EMPTY"])("documents %s at either edge of its name", (name) => {+ const s = state(`<?php ${name}($value);`);+ for (const pos of [6, 8, 6 + name.length]) {+ const doc = phpConstructAt(s, pos, "php");+ expect(doc).toMatchObject({ from: 6, to: 6 + name.length });+ expect(doc?.markdown).toContain("PHP language construct");+ expect(doc?.markdown).toContain(`function.${name.toLowerCase()}.php`);+ }+ });++ it.each([+ '<?php $empty = "empty($x)";',+ "<?php // empty($x)",+ "<?php /* empty($x) */",+ "<?php $obj->empty();",+ "<?php $obj?->empty();",+ "<?php Foo::empty();",+ "<?php Foo\\empty();",+ "<?php function empty() {}",+ "<p>empty($x)</p><?php echo 1;",+ ])("does not hijack other occurrences: %s", (text) => {+ const s = state(text);+ for (const match of text.matchAll(/empty/g)) expect(phpConstructAt(s, match.index + 2, "php")).toBeNull();+ });++ it("does not attach PHP docs to other languages or ordinary functions", () => {+ expect(phpConstructAt(state("<?php empty($x);"), 8, "javascript")).toBeNull();+ expect(phpConstructDocumentation("PHP", "strtoupper")).toBeNull();+ expect(phpConstructDocumentation("php", "constructor")).toBeNull();+ });++ it("serves hover, declaration and quick definition without a running server", async () => {+ const view = new EditorView({+ state: EditorState.create({+ doc: "<?php empty($value);",+ selection: { anchor: 8 },+ extensions: [php, lspDoc.of({ doc: 1, path: "/p/a.php", language: "php", uiMode: "PHP", readOnly: false })],+ }),+ parent: document.body,+ });+ views.push(view);+ expect((await requestHover(view, 8))?.contents.value).toContain("empty(mixed $var): bool");+ for (const action of [+ () => gotoTargets(view, "definition"),+ () => gotoTargets(view, "declaration"),+ () => quickDefinition(view),+ ]) {+ await action();+ const popup = useLspPopup.getState().popup;+ expect(popup?.kind).toBe("doc");+ if (popup?.kind === "doc") expect(popup.entries[0]?.markup.value).toContain("no source declaration");+ closePopup();+ }+ });+});diff --git a/src/editor/lsp/phpConstructs.ts b/src/editor/lsp/phpConstructs.tsnew file mode 100644index 000000000..47dd905fb--- /dev/null+++ b/src/editor/lsp/phpConstructs.ts@@ -0,0 +1,40 @@+import type { EditorState } from "@codemirror/state";+import { syntaxTree } from "@codemirror/language";++const CONSTRUCTS: Readonly<Record<string, { signature: string; description: string }>> = {+ empty: {+ signature: "empty(mixed $var): bool",+ description:+ "Returns true when the value is falsey or the variable does not exist. Checking an undefined variable does not emit a warning.",+ },+ isset: {+ signature: "isset(mixed $var, mixed ...$vars): bool",+ description:+ "Returns true only when every supplied variable exists and is not null. Checks stop at the first unset or null variable.",+ },+};++export function phpConstructDocumentation(language: string | null, name: string): string | null {+ if (language?.toLowerCase() !== "php") return null;+ const key = name.toLowerCase();+ const entry = Object.hasOwn(CONSTRUCTS, key) ? CONSTRUCTS[key] : undefined;+ if (!entry) return null;+ return [+ "```php\n" + entry.signature + "\n```",+ entry.description,+ "PHP language construct; there is no source declaration to navigate to.",+ `[PHP manual](https://www.php.net/manual/en/function.${key}.php)`,+ ].join("\n\n");+}++/** Only an unqualified call, never a method, variable, string, comment or HTML text. */+export function phpConstructAt(state: EditorState, pos: number, language: string | null) {+ if (language?.toLowerCase() !== "php") return null;+ for (const side of [-1, 1] as const) {+ const node = syntaxTree(state).resolveInner(pos, side);+ if (node.name !== "Name" || node.parent?.name !== "CallExpression" || node.parent.from !== node.from) continue;+ const markdown = phpConstructDocumentation(language, state.sliceDoc(node.from, node.to));+ if (markdown) return { from: node.from, to: node.to, markdown };+ }+ return null;+}diff --git a/src/editor/lsp/rename.ts b/src/editor/lsp/rename.tsindex 1726b6d20..a7fb98924 100644--- a/src/editor/lsp/rename.ts+++ b/src/editor/lsp/rename.ts@@ -11,10 +11,10 @@* symbols — is left to the server. Ambiguous cases ask first.*/import type { EditorView } from "@codemirror/view";-import { commands, isCancelled, type Pos, type WorkspaceEdit } from "@/platform/ipc";+import { commands, isCancelled, unavailableText, type Pos, type WorkspaceEdit } from "@/platform/ipc";import { whenSynced, type EditorDocContext } from "@/editor/api";import { structure } from "@/editor/structure";-import { docOf, lspRequest, reportLspError } from "./lsp";+import { docOf, isUnavailable, lspRequest, reportLspError } from "./lsp";import { comparePos, offsetToPos, rangeToOffsets } from "./positions";import { showHint } from "./hint";import { caretAnchor, openPopup, type PreviewOccurrence } from "./popupStore";@@ -69,7 +69,7 @@ export async function startRename(view: EditorView) {range = await lspRequest(() => commands.lspPrepareRename(doc.doc, pos));} catch (e) {if (isCancelled(e)) return;- if (!(await startSyntaxRename(view, doc, pos))) reportLspError(view, e, true);+ if (!(await startSyntaxRename(view, doc, pos, e))) reportLspError(view, e, true);return;}if (!range) {@@ -258,7 +258,7 @@ async function syntaxPlan(view: EditorView, doc: EditorDocContext, pos: Pos): Pr}/** Opens the rename popup for a syntax-based local rename. False when the fallback can't help. */-async function startSyntaxRename(view: EditorView, doc: EditorDocContext, pos: Pos): Promise<boolean> {+async function startSyntaxRename(view: EditorView, doc: EditorDocContext, pos: Pos, cause?: unknown): Promise<boolean> {let result;try {await whenSynced(view);@@ -269,7 +269,8 @@ async function startSyntaxRename(view: EditorView, doc: EditorDocContext, pos: P}if (result.kind === "unsupported") return false;if (result.kind === "refused") {- showHint(view, result.message);+ const reason = isUnavailable(cause) ? unavailableText(cause) : cause instanceof Error ? cause.message : null;+ showHint(view, reason ? `${reason}. ${result.message}` : result.message);return true;}const { plan } = result;diff --git a/src/editor/lsp/syntaxFallback.test.ts b/src/editor/lsp/syntaxFallback.test.tsindex e709a8e31..000278996 100644--- a/src/editor/lsp/syntaxFallback.test.ts+++ b/src/editor/lsp/syntaxFallback.test.ts@@ -350,6 +350,24 @@ describe("navigation wiring", () => {});describe("rename wiring", () => {+ it("preserves the server's missing capability when syntax cannot rename a method", async () => {+ cmd.lspPrepareRename.mockReturnValueOnce(+ Promise.resolve({+ status: "error",+ error: { kind: "unavailable", message: "intelephense doesn't support rename" },+ }),+ );+ cmd.syntaxLocals.mockReturnValueOnce(ok({ status: "notLocal", name: "run", range: r(0, 4, 7), reason: "member" }));+ const view = editor("obj.run();", "php", 5);+ await startRename(view);+ const message = document.querySelector(".cm-lsp-hint")?.textContent;+ expect(message).toContain("intelephense doesn't support rename");+ expect(message).toContain("only local variables");+ expect(message).not.toContain("without the language server");+ expect(view.state.doc.toString()).toBe("obj.run();");+ expect(useLspPopup.getState().popup).toBeNull();+ });+it("renames a certain local in place when the server is not ready", async () => {cmd.syntaxLocals.mockReturnValueOnce(ok(local({ references: [r(1, 4, 5)] })));cmd.syntaxNodeAtdiff --git a/src/editor/lsp/syntaxFallback.ts b/src/editor/lsp/syntaxFallback.tsindex 496c0e1e2..f9ad9334c 100644--- a/src/editor/lsp/syntaxFallback.ts+++ b/src/editor/lsp/syntaxFallback.ts@@ -243,7 +243,7 @@ export async function planLocalRename(if (locals.status === "notLocal")return {kind: "refused",- message: tx`Can't rename '${locals.name}' without the language server: only local variables can be renamed based on syntax`,+ message: tx`Can't rename '${locals.name}' based on syntax: only local variables can be renamed this way`,};const { symbol } = locals;const ranges = [symbol.definition, ...symbol.references].sort((a, b) => comparePos(a.start, b.start));diff --git a/src/platform/locales/text/zh.json b/src/platform/locales/text/zh.jsonindex b8242c554..7115b7777 100644--- a/src/platform/locales/text/zh.json+++ b/src/platform/locales/text/zh.json@@ -3806,7 +3806,6 @@"Save '{word}' to project-level dictionary": "将 '{word}' 保存到项目级词典","Save '{word}' to application-level dictionary": "将 '{word}' 保存到应用程序级词典","Typo: In word '{word}'": "拼写错误:单词 '{word}'",- "Can't rename '{name}' without the language server: only local variables can be renamed based on syntax": "没有语言服务器时无法重命名 '{name}':基于语法只能重命名局部变量","Choose Super Class or Interface ({count} found)": "选择超类或接口(找到 {count} 个)","Choose Super Method of {name} ({count} found)": "选择 {name} 的超方法(找到 {count} 个)","Choose Implementation of {name} ({count} found)": "选择 {name} 的实现(找到 {count} 个)",@@ -4959,5 +4958,8 @@"Tomcat server.xml has no HTTP connector": "Tomcat 的 server.xml 中没有 HTTP 连接器","WAR contains an invalid path": "WAR 中包含无效路径","Context path must start with / and contain only letters, digits, /, - or _": "上下文路径必须以 / 开头,且只能包含字母、数字、/、- 或 _",- "Tomcat home must contain bin/catalina.sh or bin/catalina.bat and lib/catalina.jar": "Tomcat 安装目录必须包含 bin/catalina.sh 或 bin/catalina.bat,以及 lib/catalina.jar"+ "Tomcat home must contain bin/catalina.sh or bin/catalina.bat and lib/catalina.jar": "Tomcat 安装目录必须包含 bin/catalina.sh 或 bin/catalina.bat,以及 lib/catalina.jar",+ "Can't rename '{name}' based on syntax: only local variables can be renamed this way": "无法基于语法重命名 '{name}':这种方式只能重命名局部变量",+ "Returns true when the value is falsey or the variable does not exist. Checking an undefined variable does not emit a warning.": "当值为假值或变量不存在时返回 true。检查未定义的变量不会产生警告。",+ "Returns true only when every supplied variable exists and is not null. Checks stop at the first unset or null variable.": "仅当传入的每个变量都存在且不为 null 时返回 true。遇到第一个未设置或为 null 的变量即停止检查。"}