Lsp Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravel/lsp
   

   Add the service provider to config/app.php:

   'providers' => [
       Laravel\Lsp\LspServiceProvider::class,
   ],
   

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="Laravel\Lsp\LspServiceProvider" --tag="lsp-config"
   

   Edit config/lsp.php to define your preferred language server settings (e.g., PHPStan, Psalm, Intelephense).

3. First Use Case: Run the language server locally for testing:

   php artisan lsp:serve
   

   Configure your IDE (e.g., VS Code) to connect to localhost:3200 via the Language Server Protocol (LSP) extension.

Key Files to Review

• config/lsp.php: Central configuration for language servers, analysis tools, and IDE integrations.
• routes/lsp.php: Define custom LSP endpoints (if extending functionality).
• app/Providers/LspServiceProvider.php: Bootstrapping logic for the LSP server.

Implementation Patterns

Core Workflows

1. Tool Integration:

   • Use config/lsp.php to define analysis tools (e.g., PHPStan, Psalm, Intelephense) with their respective configs:

     'tools' => [
         'phpstan' => [
             'enabled' => true,
             'config' => base_path('phpstan.neon'),
         ],
         'psalm' => [
             'enabled' => true,
             'config' => base_path('psalm.xml'),
         ],
     ],
     

   • Tools are automatically invoked during LSP requests (e.g., code analysis, autocompletion).

2. Custom Commands: Extend the LSP server with custom commands by publishing a command class and binding it in the service provider:

   // In LspServiceProvider.php
   $this->app->bind(LspCommand::class, function () {
       return new CustomLspCommand();
   });
   

3. IDE-Specific Configurations:

   • Configure IDE-specific settings (e.g., VS Code settings.json):

     {
         "laravel.lsp.server": "http://localhost:3200",
         "laravel.lsp.tools": ["phpstan", "psalm"]
     }
     

   • Use config/lsp.php to define IDE-specific overrides:

     'ide' => [
         'vscode' => [
             'autocomplete' => true,
             'hover' => ['phpdoc', 'source'],
         ],
     ],
     

4. Real-Time Feedback: Leverage the LSP server for real-time feedback during development:

   • Autocompletion: Triggered via IDE shortcuts (e.g., Ctrl+Space).
   • Diagnostics: Errors/warnings appear inline in the IDE (powered by PHPStan/Psalm).
   • Go-to-Definition: Press F12 (or equivalent) to jump to the definition of classes/methods.

Integration Tips

• CI/CD Pipelines: Use the LSP server to validate code quality in CI by running:

  php artisan lsp:validate
  

  This triggers all enabled tools (e.g., PHPStan, Psalm) and fails the build on errors.

• Monorepos: Configure the LSP server to scan multiple projects by extending the LspServiceProvider:

  public function boot()
  {
      $this->app['lsp']->addProject(base_path('../project-b'));
  }
  

• Custom Analysis: Extend the LSP server to support custom analysis rules by creating a LspAnalyzer class and registering it:

  $this->app->bind(Laravel\Lsp\Contracts\Analyzer::class, CustomAnalyzer::class);
  

Gotchas and Tips

Common Pitfalls

1. Tool Conflicts:

   • Avoid enabling multiple static analyzers (e.g., PHPStan + Psalm) if they conflict. Configure config/lsp.php to prioritize one:

     'tools' => [
         'phpstan' => ['enabled' => true, 'priority' => 1],
         'psalm' => ['enabled' => false], // Disable to avoid conflicts
     ],
     

2. Performance Overhead:

   • Heavy tools (e.g., Psalm with strict rules) can slow down the LSP server. Optimize by:
     • Running tools in the background with php artisan lsp:watch.
     • Using --memory-limit in tool configs (e.g., phpstan.neon).

3. IDE Connection Issues:

   • Ensure the LSP server is running (php artisan lsp:serve) and the IDE is configured to point to the correct URL (http://localhost:3200 by default).
   • Check for firewall/port conflicts if the connection fails.

4. Caching:

   • The LSP server caches analysis results. Clear the cache when tool configs change:

     php artisan lsp:clear-cache
     

Debugging Tips

1. Enable Verbose Logging: Set the debug flag in config/lsp.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs will appear in storage/logs/lsp.log.

2. Tool-Specific Debugging:

   • For PHPStan/Psalm, use their respective debug flags:

     php artisan lsp:debug --tool=phpstan
     

   • Check tool-specific logs (e.g., storage/logs/phpstan.log).

3. LSP Protocol Inspection: Use the lsp:inspect command to dump raw LSP requests/responses:

   php artisan lsp:inspect --request=textDocument/completion
   

Extension Points

1. Custom Language Servers: Extend the LSP server to support additional languages (e.g., JavaScript, TypeScript) by implementing Laravel\Lsp\Contracts\LanguageServer.

2. Dynamic Tool Loading: Dynamically load tools based on environment variables or user input:

   // In LspServiceProvider.php
   $enabledTools = explode(',', env('LSP_ENABLED_TOOLS', 'phpstan,psalm'));
   foreach ($enabledTools as $tool) {
       $this->app['lsp']->enableTool($tool);
   }
   

3. Webhook Integration: Trigger LSP analysis via webhooks (e.g., GitHub Actions) by exposing an API endpoint:

   // In routes/lsp.php
   Route::post('/webhook/analyze', [LspController::class, 'analyze']);
   

4. Custom LSP Features: Add support for custom LSP features (e.g., code actions, document formatting) by extending the LspServer class:

   class CustomLspServer extends Laravel\Lsp\LspServer
   {
       public function registerCustomFeatures()
       {
           $this->on('textDocument/codeAction', [$this, 'handleCodeAction']);
       }
   }