Language Server Protocol Laravel Package

Getting Started

Install via composer require felixfbecker/language-server-protocol. This package provides only the protocol model classes (e.g., TextDocumentIdentifier, CompletionItem, Position, Diagnostic) — it does not implement a full language server or client. Your first step should be to examine the src/ directory structure in the repo: class names mirror LSP spec sections (e.g., TextDocument/, Workspace/, Window/). Begin by constructing a simple server skeleton that accepts JSON-RPC messages and instantiates the appropriate protocol objects to parse incoming requests (e.g., InitializeRequest, DidChangeTextDocumentParams). Use JSON_THROW_ON_ERROR (PHP ≥7.3) and json_decode($payload, true, 512, JSON_THROW_ON_ERROR) to safely decode payloads before hydrating protocol objects.

Implementation Patterns

• Hydrate from raw payloads: Use constructor signatures or factory methods to build protocol objects from decoded JSON (e.g., new CompletionParams(TextDocumentIdentifier::fromJson($json['textDocument']), Position::fromJson($json['position']), ...)).
• Strict validation: Leverage PHP 7.4+ typed properties and nullable types on protocol classes for early detection of malformed requests/responses. Wrap object construction in try/catch for TypeError or JsonException.
• Stateless request handling: Separate protocol parsing (LanguageServerProtocol\*) from business logic. For example, a CompletionHandler class accepts CompletionParams and returns CompletionList, deferring PHP-level analysis (e.g., symbol resolution) to your own service layer.
• Streaming over stdio/HTTP: Feed incoming LSP messages into a Stream (stdio or PSR-7 request body), parse JSON-RPC envelopes manually (or via a small wrapper), then dispatch to handler methods. Use ArrayObject or associative arrays temporarily for debugging before committing to typed model hydration.
• Extensibility: Many protocol classes support $additionalProperties (e.g., TextDocumentItem, CodeLens). Store LSP extension data in $additionalProperties arrays without modifying the core package.

Gotchas and Tips

• Version drift: The package lags behind latest LSP spec (e.g., no support for textDocument/implementation until v1.1.0, and typeDefinition added later). Check composer.lock to verify compatibility with your server’s expected capabilities. Prefer pinning to exact releases over ^1.0.
• Missing constructors: While core classes like Position, Range, Location have explicit __construct(), some nested objects (e.g., ParameterInformation) lack comprehensive defaults—always provide all required fields explicitly. Use get_class_vars() or IDE inspection to verify required vs optional properties.
• JSON encoding pitfalls: By default, protocol classes use public properties, not getters/setters. When serializing with json_encode(), ensure properties are not null unless explicitly allowed—nulls may be omitted or cause schema mismatches. Consider implementing JsonSerializable in your own wrappers.
• No built-in transport layer: This package does not handle WebSocket, stdio, or HTTP transport. You’ll need to integrate with something like reactphp/http, clue/php-stream-stdio, or your own PSR-15 handler.
• Testing: Mock protocol objects (not the classes themselves) to isolate logic. Use prophecy or simple arrays for param injection—most protocol classes are POPOs with no dependencies. Validate round-trips with json_encode($obj) === json_encode(Object::fromJson(json_decode(json_encode($obj), true))).