Skip to content

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.

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.ts
index 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.ts
index 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.ts
index 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" | "ty
const 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.syntaxNodeAt
diff --git a/src/editor/lsp/syntaxFallback.ts b/src/editor/lsp/syntaxFallback.ts
index 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.json
index 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 的变量即停止检查。"
}