@elyracode/lsp-php 0.9.10

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [0.9.10] - 2026-06-19
+
+### Added
+- Initial release: PHP LSP integration for Elyra. Starts a PHP language server (Intelephense, with phpactor fallback) per session in projects containing a `composer.json`, and exposes `php_definitions`, `php_references`, `php_diagnostics`, and `php_hover` as agent tools.

package/README.md

@@ -0,0 +1,42 @@
+# @elyracode/lsp-php
+
+PHP LSP integration for Elyra. Starts a PHP language server process per session and exposes semantic code navigation and diagnostics as agent tools — go-to-definition, find references, hover, and diagnostics for Laravel and PHP projects.
+
+## Prerequisites
+
+A PHP language server must be available. The extension prefers [Intelephense](https://intelephense.com/) and falls back to [phpactor](https://phpactor.github.io/).
+
+Install Intelephense (recommended) globally:
+
+```bash
+npm install -g intelephense
+```
+
+…or per project:
+
+```bash
+npm install -D intelephense
+```
+
+The extension looks for `intelephense` in the project's `node_modules/.bin/` first, then a global `intelephense`, then a global `phpactor`.
+
+A `composer.json` must exist in the project root. The extension does nothing if one is not found.
+
+> Note: Intelephense's core navigation (definitions, references, hover, diagnostics) works with the free tier. A licence key only unlocks additional premium features.
+
+## Installation
+
+```bash
+elyra install npm:@elyracode/lsp-php
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `php_definitions` | Go to the definition of a PHP symbol at a given file position |
+| `php_references` | Find all references to a PHP symbol across the project |
+| `php_diagnostics` | Get PHP errors and warnings for a file |
+| `php_hover` | Get type information and PHPDoc for a symbol |
+
+All tools accept 1-based line and column numbers and return human-readable text results. The first call after a session starts may take a moment while the language server indexes the workspace.

package/extensions/index.ts

@@ -0,0 +1,484 @@
+import type { ExtensionAPI } from "@elyracode/coding-agent";
+import { type ChildProcess, execSync, spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Type } from "typebox";
+
+// ── LSP Types ───────────────────────────────────────────────────────────────
+
+interface LspPosition {
+	line: number;
+	character: number;
+}
+
+interface LspRange {
+	start: LspPosition;
+	end: LspPosition;
+}
+
+interface LspLocation {
+	uri: string;
+	range: LspRange;
+}
+
+interface LspDiagnostic {
+	range: LspRange;
+	severity?: number;
+	message: string;
+	source?: string;
+	code?: string | number;
+}
+
+interface LspHoverResult {
+	contents: string | { kind: string; value: string } | Array<string | { kind: string; value: string }>;
+	range?: LspRange;
+}
+
+interface PendingRequest {
+	resolve: (value: unknown) => void;
+	reject: (reason: unknown) => void;
+}
+
+/** A discovered PHP language server: how to launch it. */
+interface PhpLanguageServer {
+	command: string;
+	args: string[];
+	name: string;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+const SEVERITY_LABELS: Record<number, string> = {
+	1: "Error",
+	2: "Warning",
+	3: "Information",
+	4: "Hint",
+};
+
+function fileUri(filePath: string): string {
+	return `file://${filePath}`;
+}
+
+function uriToPath(uri: string): string {
+	return uri.replace(/^file:\/\//, "");
+}
+
+function positionFromLineCol(line: number, col: number): LspPosition {
+	return { line: line - 1, character: col - 1 };
+}
+
+function whichBinary(name: string): string | undefined {
+	try {
+		const found = execSync(`which ${name}`, {
+			encoding: "utf-8",
+			timeout: 5000,
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		return found || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Locate a PHP language server. Prefers Intelephense (npm-installable, the most
+ * common choice), then phpactor. Returns how to launch it, or undefined.
+ */
+function findLanguageServer(workingDir: string): PhpLanguageServer | undefined {
+	const localIntelephense = join(workingDir, "node_modules", ".bin", "intelephense");
+	if (existsSync(localIntelephense)) {
+		return { command: localIntelephense, args: ["--stdio"], name: "intelephense" };
+	}
+
+	const globalIntelephense = whichBinary("intelephense");
+	if (globalIntelephense) {
+		return { command: globalIntelephense, args: ["--stdio"], name: "intelephense" };
+	}
+
+	const phpactor = whichBinary("phpactor");
+	if (phpactor) {
+		return { command: phpactor, args: ["language-server"], name: "phpactor" };
+	}
+
+	return undefined;
+}
+
+// ── Extension ───────────────────────────────────────────────────────────────
+
+export default function (elyra: ExtensionAPI): void {
+	let lspProcess: ChildProcess | null = null;
+	let requestId = 0;
+	const pendingRequests = new Map<number, PendingRequest>();
+	let buffer = Buffer.alloc(0);
+	let initialized = false;
+	let cwd = "";
+	const openedFiles = new Set<string>();
+	const diagnosticsByUri = new Map<string, LspDiagnostic[]>();
+
+	// ── JSON-RPC Client ─────────────────────────────────────────────────
+
+	function sendRequest(method: string, params: unknown): Promise<unknown> {
+		if (!lspProcess?.stdin) {
+			return Promise.reject(new Error("LSP server not running"));
+		}
+		const id = ++requestId;
+		const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+		const message = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+		lspProcess.stdin.write(message);
+
+		return new Promise<unknown>((res, rej) => {
+			const timer = setTimeout(() => {
+				pendingRequests.delete(id);
+				rej(new Error(`LSP request "${method}" timed out after 15s`));
+			}, 15_000);
+
+			pendingRequests.set(id, {
+				resolve: (value: unknown) => {
+					clearTimeout(timer);
+					res(value);
+				},
+				reject: (reason: unknown) => {
+					clearTimeout(timer);
+					rej(reason);
+				},
+			});
+		});
+	}
+
+	function sendNotification(method: string, params: unknown): void {
+		if (!lspProcess?.stdin) return;
+		const body = JSON.stringify({ jsonrpc: "2.0", method, params });
+		const message = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+		lspProcess.stdin.write(message);
+	}
+
+	function handleData(chunk: Buffer): void {
+		buffer = Buffer.concat([buffer, chunk]);
+
+		for (;;) {
+			const headerEnd = buffer.indexOf("\r\n\r\n");
+			if (headerEnd === -1) break;
+
+			const header = buffer.subarray(0, headerEnd).toString("utf-8");
+			const match = /Content-Length:\s*(\d+)/i.exec(header);
+			if (!match) {
+				buffer = buffer.subarray(headerEnd + 4);
+				continue;
+			}
+
+			const contentLength = parseInt(match[1], 10);
+			const bodyStart = headerEnd + 4;
+			if (buffer.length < bodyStart + contentLength) break;
+
+			const bodyStr = buffer.subarray(bodyStart, bodyStart + contentLength).toString("utf-8");
+			buffer = buffer.subarray(bodyStart + contentLength);
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(bodyStr);
+			} catch {
+				continue;
+			}
+
+			if (!parsed || typeof parsed !== "object") continue;
+			const msg = parsed as Record<string, unknown>;
+
+			// Response to a request
+			if ("id" in msg && typeof msg.id === "number") {
+				const pending = pendingRequests.get(msg.id);
+				if (pending) {
+					pendingRequests.delete(msg.id);
+					if ("error" in msg && msg.error) {
+						const err = msg.error as { code: number; message: string };
+						pending.reject(new Error(`LSP error ${err.code}: ${err.message}`));
+					} else {
+						pending.resolve(msg.result);
+					}
+				}
+			}
+
+			// Server notification
+			if ("method" in msg && typeof msg.method === "string") {
+				if (msg.method === "textDocument/publishDiagnostics" && msg.params) {
+					const p = msg.params as { uri: string; diagnostics: LspDiagnostic[] };
+					diagnosticsByUri.set(p.uri, p.diagnostics);
+				}
+			}
+		}
+	}
+
+	// ── File helpers ────────────────────────────────────────────────────
+
+	function openFile(filePath: string): void {
+		const absPath = resolve(cwd, filePath);
+		const uri = fileUri(absPath);
+		if (openedFiles.has(uri)) return;
+
+		let text: string;
+		try {
+			text = readFileSync(absPath, "utf-8");
+		} catch {
+			return;
+		}
+
+		sendNotification("textDocument/didOpen", {
+			textDocument: {
+				uri,
+				languageId: "php",
+				version: 1,
+				text,
+			},
+		});
+		openedFiles.add(uri);
+	}
+
+	function formatLocations(result: unknown, workingDir: string): string {
+		if (!result) return "No results found.";
+
+		const locations: LspLocation[] = Array.isArray(result) ? result : [result as LspLocation];
+		if (locations.length === 0) return "No results found.";
+
+		const prefix = workingDir + "/";
+		return locations
+			.map((loc) => {
+				const p = uriToPath(loc.uri);
+				const rel = p.startsWith(prefix) ? p.slice(prefix.length) : p;
+				return `${rel}:${loc.range.start.line + 1}:${loc.range.start.character + 1}`;
+			})
+			.join("\n");
+	}
+
+	// ── Lifecycle ───────────────────────────────────────────────────────
+
+	elyra.on("session_start", async (_event, ctx) => {
+		cwd = ctx.cwd;
+
+		// PHP/Laravel projects are identified by composer.json.
+		if (!existsSync(join(cwd, "composer.json"))) return;
+
+		const server = findLanguageServer(cwd);
+		if (!server) return;
+
+		lspProcess = spawn(server.command, server.args, { cwd });
+
+		lspProcess.stdout?.on("data", (chunk: Buffer) => handleData(chunk));
+		lspProcess.stderr?.on("data", () => {
+			/* ignore stderr */
+		});
+		lspProcess.on("exit", () => {
+			lspProcess = null;
+			initialized = false;
+		});
+
+		try {
+			await sendRequest("initialize", {
+				processId: process.pid,
+				capabilities: {},
+				rootUri: fileUri(cwd),
+				workspaceFolders: [{ uri: fileUri(cwd), name: "workspace" }],
+			});
+			sendNotification("initialized", {});
+			initialized = true;
+		} catch {
+			lspProcess?.kill();
+			lspProcess = null;
+			return;
+		}
+
+		// ── Tool: php_definitions ───────────────────────────────────────
+
+		elyra.registerTool({
+			name: "php_definitions",
+			label: "PHP Go to Definition",
+			description:
+				"Go to the definition of a PHP symbol at a given position. Returns the file path and " +
+				"line where the symbol is defined. More precise than grep for finding where classes, " +
+				"methods, functions, properties, and traits are declared in Laravel and PHP projects.",
+			promptSnippet: "Go to definition of a PHP symbol at a file position",
+			parameters: Type.Object({
+				file: Type.String({ description: "Relative file path from project root" }),
+				line: Type.Number({ description: "Line number (1-based)" }),
+				column: Type.Number({ description: "Column number (1-based)" }),
+			}),
+			execute: async (_toolCallId, params) => {
+				if (!initialized) {
+					return { content: [{ type: "text", text: "Error: PHP language server is not running." }], details: {} };
+				}
+
+				const absPath = resolve(cwd, params.file);
+				openFile(params.file);
+
+				try {
+					const result = await sendRequest("textDocument/definition", {
+						textDocument: { uri: fileUri(absPath) },
+						position: positionFromLineCol(params.line, params.column),
+					});
+					return { content: [{ type: "text", text: formatLocations(result, cwd) }], details: {} };
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					return { content: [{ type: "text", text: `Error: ${message}` }], details: {} };
+				}
+			},
+		});
+
+		// ── Tool: php_references ────────────────────────────────────────
+
+		elyra.registerTool({
+			name: "php_references",
+			label: "PHP Find References",
+			description:
+				"Find all references to a PHP symbol at a given position. Returns every location where " +
+				"the symbol is used across the project. More precise than grep for understanding how a " +
+				"class, method, or function is used in a Laravel or PHP codebase.",
+			promptSnippet: "Find all references to a PHP symbol at a file position",
+			parameters: Type.Object({
+				file: Type.String({ description: "Relative file path from project root" }),
+				line: Type.Number({ description: "Line number (1-based)" }),
+				column: Type.Number({ description: "Column number (1-based)" }),
+			}),
+			execute: async (_toolCallId, params) => {
+				if (!initialized) {
+					return { content: [{ type: "text", text: "Error: PHP language server is not running." }], details: {} };
+				}
+
+				const absPath = resolve(cwd, params.file);
+				openFile(params.file);
+
+				try {
+					const result = await sendRequest("textDocument/references", {
+						textDocument: { uri: fileUri(absPath) },
+						position: positionFromLineCol(params.line, params.column),
+						context: { includeDeclaration: true },
+					});
+					return { content: [{ type: "text", text: formatLocations(result, cwd) }], details: {} };
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					return { content: [{ type: "text", text: `Error: ${message}` }], details: {} };
+				}
+			},
+		});
+
+		// ── Tool: php_diagnostics ───────────────────────────────────────
+
+		elyra.registerTool({
+			name: "php_diagnostics",
+			label: "PHP Diagnostics",
+			description:
+				"Get PHP errors and warnings for a file from the language server (undefined symbols, " +
+				"type issues, unused imports, and more). Returns diagnostics with line numbers, severity, " +
+				"and messages.",
+			promptSnippet: "Get PHP errors and warnings for a file",
+			parameters: Type.Object({
+				file: Type.String({ description: "Relative file path from project root" }),
+			}),
+			execute: async (_toolCallId, params) => {
+				if (!initialized) {
+					return { content: [{ type: "text", text: "Error: PHP language server is not running." }], details: {} };
+				}
+
+				const absPath = resolve(cwd, params.file);
+				openFile(params.file);
+
+				const uri = fileUri(absPath);
+
+				// Allow the server time to publish diagnostics after opening the file.
+				// Intelephense indexes the workspace on first use, so give it a moment.
+				await new Promise<void>((r) => setTimeout(r, 1500));
+
+				const diagnostics = diagnosticsByUri.get(uri) ?? [];
+				if (diagnostics.length === 0) {
+					return { content: [{ type: "text", text: "No diagnostics found." }], details: {} };
+				}
+
+				const lines = diagnostics.map((d) => {
+					const severity = SEVERITY_LABELS[d.severity ?? 1] ?? "Unknown";
+					const loc = `${params.file}:${d.range.start.line + 1}:${d.range.start.character + 1}`;
+					const code = d.code ? ` [${d.code}]` : "";
+					return `${severity}${code} ${loc}: ${d.message}`;
+				});
+
+				return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+			},
+		});
+
+		// ── Tool: php_hover ─────────────────────────────────────────────
+
+		elyra.registerTool({
+			name: "php_hover",
+			label: "PHP Hover",
+			description:
+				"Get type information and documentation for a PHP symbol at a given position. Shows the " +
+				"resolved signature and PHPDoc comments for classes, methods, and functions.",
+			promptSnippet: "Get type info and docs for a PHP symbol at a file position",
+			parameters: Type.Object({
+				file: Type.String({ description: "Relative file path from project root" }),
+				line: Type.Number({ description: "Line number (1-based)" }),
+				column: Type.Number({ description: "Column number (1-based)" }),
+			}),
+			execute: async (_toolCallId, params) => {
+				if (!initialized) {
+					return { content: [{ type: "text", text: "Error: PHP language server is not running." }], details: {} };
+				}
+
+				const absPath = resolve(cwd, params.file);
+				openFile(params.file);
+
+				try {
+					const result = await sendRequest("textDocument/hover", {
+						textDocument: { uri: fileUri(absPath) },
+						position: positionFromLineCol(params.line, params.column),
+					});
+
+					if (!result) {
+						return { content: [{ type: "text", text: "No hover information available." }], details: {} };
+					}
+
+					const hover = result as LspHoverResult;
+					let text: string;
+
+					if (typeof hover.contents === "string") {
+						text = hover.contents;
+					} else if (Array.isArray(hover.contents)) {
+						text = hover.contents.map((c) => (typeof c === "string" ? c : c.value)).join("\n\n");
+					} else {
+						text = hover.contents.value;
+					}
+
+					return {
+						content: [{ type: "text", text: text || "No hover information available." }],
+						details: {},
+					};
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					return { content: [{ type: "text", text: `Error: ${message}` }], details: {} };
+				}
+			},
+		});
+	});
+
+	// ── Shutdown ────────────────────────────────────────────────────────
+
+	elyra.on("session_shutdown", async () => {
+		if (lspProcess && initialized) {
+			try {
+				await sendRequest("shutdown", null);
+				sendNotification("exit", null);
+			} catch {
+				// ignore errors during shutdown
+			}
+		}
+		if (lspProcess) {
+			lspProcess.kill();
+			lspProcess = null;
+		}
+		initialized = false;
+		openedFiles.clear();
+		diagnosticsByUri.clear();
+		buffer = Buffer.alloc(0);
+		requestId = 0;
+		for (const pending of pendingRequests.values()) {
+			pending.reject(new Error("LSP server shutting down"));
+		}
+		pendingRequests.clear();
+	});
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@elyracode/lsp-php",
+  "version": "0.9.10",
+  "description": "PHP LSP integration for Elyra — semantic code navigation and diagnostics for Laravel and PHP projects",
+  "type": "module",
+  "keywords": [
+    "elyra-package",
+    "lsp",
+    "php",
+    "laravel",
+    "intelephense"
+  ],
+  "license": "MIT",
+  "author": "Knut W. Horne",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwhorne/elyra.git",
+    "directory": "packages/lsp-php"
+  },
+  "elyra": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@elyracode/coding-agent": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  }
+}