README

This package transpiles the microsoft/lsprotocol/generator/lsp.json to PHP, providing the protocol classes required to create Language Server with PHP.

A lot of inspiration and some code was taken from phpactor/language-server-protocol. The difference is, that the code generation is fully based on PHP and the protocol classes are more complete.

Allthough the lsp.json states, that the version of the LSP is a specific version, there are some code parts, which are "proposed" or from future versions. Allthough this is part of the official protocol definition, part of the official code generator inside the microsoft/lsprotocol project and also part of the official vscode-language-server-protocol project, we filter those parts out in the default build. You can build your own set of classes including those future parts of the specification, but you need to be careful when using them

This Library will stick to the current official set of features.

Generation

Generating the code:

• composer build

Generate a specific protocol subset (for example only features up to 3.17.0):

• php generator/generate.php --max-version=3.17.0

The version filter keeps referenced types even if they are marked with a newer since value (for example type renames with older sinceTags) so generation stays consistent.

Running the PHP tests:

• composer integrate

Usage

Deserialization

This library will use the type information from the lsp.json to generate fromArray static constructors for each type:

$item = CompletionItem::fromArray([
    'label' => 'Foobar',
    'kind' => 1,
    'detail' => 'This is foobar',
    'documentation' => [
        'kind' => 'markdown',
        'value' => 'Foobar',
    ],
    'additionalTextEdits' => [
        [
            'range' => [
                'start' => [
                    'line' => 5,
                    'character' => 10,
                ],
                'end' => [
                    'line' => 10,
                    'character' => 10,
                ],
            ],
            'newText' => 'Foobar',
        ],
    ],
    'command' => [
        'title' => 'Foobar',
        'command' => 'my.command',
    ],
]);

Will return a fully hydrated completion item with concrete sub-types.

NOTE: that when deserializing from a language server client request, it is probably a good idea to ignore additional parameters (the second argument to fromArray). This is because it is perfectly valid to pass unknown properties to some of the LSP objects.

Serialization

Properties in classes are public to enable JSON serialization. Call json_encode($lspObject) to get the valid LSP JSON object.

Notes on some design decisions

The LSP is defined with extending classes and using mixins. In PHP there are no mixins or multiple inheritance. So for now each class simply has no inheritance. To support mixins and extending classes, all classes would need to be based on interfaces so properties couldn't be used but getters and setters. This would lead to much more files and code. If there are no critical problems with the current design, this change will be avoided.

Contributing

This package is open source and welcomes contributions! Feel free to open a pull request on this repository.