LSParrot VS Code Extension

LSParrot is a VS Code client for the ext-lsparrot PHP extension. It starts the PHP language server over stdio by running LSParrot\start_lsp(...) inside the configured PHP CLI binary.

The extension is still a beta/prototype. Behavior may change while LSParrot's PHP extension and analyzer integrations are being developed.

Disclaimer

This software is typical AI slop software, containing code generated by AI (LLMs). That said, the generated code has been reviewed to the extent possible and corrected as appropriate. Even so, since I am the sole reviewer, it is expected to be substantially inferior to software written entirely by hand from scratch. Please use it only if you accept that.

All code in this project has been implemented according to my intent. However, legal views differ on the copyright status of code generated with LLMs, so this project is licensed under the 0BSD license.

Requirements

VS Code 1.90.0 or newer.
PHP CLI 8.2 or newer.
ext-lsparrot built or installed for the PHP CLI binary selected by lsparrot.phpPath.
Optional Composer project tools:
- vendor/bin/phpstan for PHPStan integration.
- vendor/bin/psalm for Psalm CLI integration.
- vendor/bin/psalm-language-server for Psalm Language Server integration.

Debug commands use VS Code's php debug type, so they require a PHP debugger extension that contributes that debug adapter.

Startup

When a PHP file activates the extension, LSParrot verifies that the selected PHP binary can load ext-lsparrot and exposes LSParrot\start_lsp.

The server is launched with the configured PHP runtime arguments and a bootstrap script similar to:

php [runtime options] -r 'LSParrot\start_lsp([...]);'

lsparrot.extensionPath is a debug-only fallback. If the configured PHP binary already loads ext-lsparrot, that setting is ignored. Otherwise, LSParrot uses the explicit debug path or, when enabled, auto-detects a workspace build from:

ext/modules/lsparrot.so
ext/modules/lsparrot.dylib
ext/modules/php_lsparrot.dll
ext/modules/lsparrot.dll

If the PHP binary cannot be executed or ext-lsparrot cannot be loaded, VS Code shows an error dialog, opens LSParrot settings when requested, and leaves the extension disabled until the configuration is fixed.

Use LSParrot: Show Output to inspect the exact PHP command, startup checks, client state transitions, and analyzer messages.

Features

LSParrot Engine is always enabled and provides the core PHP LSP features.
Optional PHPStan, Psalm, and Psalm Language Server backends can be selected from the LSParrot status bar item when they are available in the active Composer project.
LSParrot: PHP FuzzyFinder searches PHP classes, interfaces, traits, enums, functions, and a terminal shortcut. Default shortcuts:
- Windows/Linux: Ctrl+Shift+Backspace or Ctrl+Shift+Delete
- macOS: Cmd+Shift+Backspace or Cmd+Shift+Delete
CodeLens entries show inheritance, implementation, and override navigation when matching symbols are available.
Code generation commands can generate constructors, getters/setters, and method stubs inside the active PHP class.
LSParrot: Symfony/Laravel Artifacts searches common framework files such as controllers, routes, models, templates, and service configuration.
LSParrot: Toggle Git Blame shows Git blame inlay hints for PHP files. Cmd/Ctrl-click a blame hint to show the commit details in LSParrot output.
PHPUnit/Pest test discovery is available through VS Code's Testing view for common *Test.php, tests/**/*.php, and Tests/**/*.php paths.
LSParrot: Debug Current PHP File starts a VS Code PHP debug session for the active PHP file.

Settings

Settings are grouped in VS Code under LSParrot with child sections for PHPStan, Psalm, Psalm Language Server, and Debug.

LSParrot

Setting	Default	Description
`lsparrot.enabled`	`true`	Enables or disables the extension.
`lsparrot.phpPath`	`php`	PHP CLI executable used to start the LSP server.
`lsparrot.additionalAnalyzer`	`[]`	Additional analyzer backends. `LSParrot Engine` always runs. Allowed values: `phpstan`, `psalm`, `psalm-ls`.
`lsparrot.phpArgs`	`[]`	Extra PHP arguments passed before the bootstrap code.
`lsparrot.phpMemoryLimit`	`-1`	`memory_limit` for LSParrot and analyzer PHP processes. Use an empty string to keep PHP defaults.
`lsparrot.enableJit`	`true`	Enables OPcache JIT for CLI processes when OPcache is available.
`lsparrot.jitBufferSize`	`32M`	`opcache.jit_buffer_size` used when JIT is enabled.
`lsparrot.jitMode`	`tracing`	`opcache.jit` mode used when JIT is enabled.
`lsparrot.symbolIndexSize`	`64M`	Memory reserved for the LSParrot project symbol index.
`lsparrot.workerCount`	`0`	PHPStan/Psalm worker count when supported. `0` lets LSParrot choose.
`lsparrot.analyzerDiagnosticsTimeout`	`60`	Seconds to wait for PHPStan/Psalm diagnostics before publishing LSParrot Engine diagnostics only.

PHPStan

Setting	Default	Description
`lsparrot.phpstanLevel`	`6`	PHPStan level used only when no PHPStan config exists in the Composer project. Level 6 is used as an existing-project-friendly default. Ignored when `phpstan.neon`, `phpstan.neon.dist`, `phpstan.dist.neon`, `.phpstan.neon`, or `.phpstan.neon.dist` exists.

Psalm

Setting	Default	Description
`lsparrot.psalmLevel`	`6`	Psalm error level used only when no `psalm.xml` or `psalm.xml.dist` exists in the Composer project. Psalm normally recommends `psalm --init` to select a project-specific level; level 6 is used here as a lenient fallback for existing projects.
`lsparrot.psalm.showInfo`	`false`	Shows Psalm informational diagnostics.
`lsparrot.psalm.liveDeadCodeDiagnostics`	`false`	Enables Psalm dead-code style diagnostics during live analysis.

Psalm Language Server

Setting	Default	Description
`lsparrot.psalm.transport`	`auto`	Psalm backend transport. `auto` prefers Psalm Language Server when available and falls back to CLI.
`lsparrot.psalm.onChange`	`true`	Forwards document changes to Psalm Language Server.
`lsparrot.psalm.onChangeDebounceMs`	`500`	Debounce delay for on-change Psalm LS analysis.
`lsparrot.psalm.maxResponseWaitMs`	`200`	Maximum time LSParrot waits for Psalm LS before returning LSParrot Engine results.
`lsparrot.psalm.enableAutocomplete`	`true`	Enables Psalm LS completion integration.
`lsparrot.psalm.enableDiagnostics`	`true`	Enables Psalm LS diagnostics.
`lsparrot.psalm.enableHover`	`true`	Enables Psalm LS hover integration.
`lsparrot.psalm.enableDefinition`	`true`	Enables Psalm LS definition integration.
`lsparrot.psalm.enableSignatureHelp`	`true`	Enables Psalm LS signature help integration.
`lsparrot.psalm.inMemory`	`false`	Passes Psalm LS in-memory mode through to Psalm. Leave disabled unless you specifically need that Psalm behavior.

Debug

Setting	Default	Description
`lsparrot.extensionPath`	`""`	Debug-only path or name for the `ext-lsparrot` binary, passed as `-dextension=...` only when PHP does not already load LSParrot.
`lsparrot.autoDetectWorkspaceExtension`	`true`	Auto-loads a workspace build from `ext/modules/*` when `ext-lsparrot` is not already available.

Project Files And Caches

LSParrot stores project-local extension state under .lsparrot in the active Composer project.

.lsparrot/vscode_config.json stores project-local analyzer selections and analyzer level defaults.
.lsparrot/lsparrot-index.bin stores the LSParrot symbol index and is reused when the PHP/Composer metadata fingerprint still matches.
.lsparrot/phpstan/cache and .lsparrot/psalm/cache store analyzer caches for LSParrot-managed PHPStan and Psalm runs.

Set LSPARROT_NO_INDEX=1 to skip loading and saving the serialized LSParrot symbol index.

Development

npm run check
npm run bundle
npm run package

Tags matching X.Y.Z trigger the GitHub Actions publish workflow. The workflow updates extension version metadata, builds the VSIX, creates a GitHub Release with generated notes and the VSIX asset, and publishes to the Visual Studio Marketplace publisher LSParrot.

License

0BSD

LSParrot VSCode Client (beta)

LSParrot-PHP