Laravel LSP — Language Server Protocol에 의한 IDE 기능 확장

이 글은 v0.0.19, 2026년 6월 시점의 초기 조사입니다. Packagist 등록 전으로 composer로 설치는 아직 할 수 없습니다.

Laravel LSP란

Laravel LSP (Language Server Protocol)는 Laravel 프레임워크를 인식한 IDE 기능을 에디터에 제공하는 공식 도구입니다. Language Server Protocol은 LSP 클라이언트(에디터 등)와 LSP 서버(Laravel LSP) 사이에서 통신하는 표준 프로토콜로, 이를 통해 여러 에디터에서 통일된 개발 경험을 실현합니다. Laravel LSP가 제공하는 기능:

자동완성 — 라우트, 뷰, 설정 키, 번역 키, Livewire 컴포넌트 등의 자동완성
호버 정보 — 커서를 올리면 설명이나 문서, 컨텍스트 정보를 표시
진단 — 코드 상의 문제를 실시간 검출
문서 링크 — 파일이나 리소스 간의 링크 기능
퀵 픽스 — 일반적인 문제의 자동 수정 제안
정의로 점프 — 심볼의 정의 위치로 이동

왜 필요한가

에디터 표준의 PHP 자동완성으로는 Laravel 프레임워크의 추상화 레이어를 이해할 수 없습니다. 예를 들어:

Route::get()의 첫 번째 인자에 URI 패턴을 입력해도 자동완성이 없음
view('users.index')의 뷰 이름을 입력해도, 실제 뷰 파일명이 자동완성되지 않음
설정 파일의 키(config('app.name'))나 번역 키(trans('messages.welcome'))는 자동완성 대상 외
Blade 템플릿 내에서의 자동완성이나 검증도 에디터 표준으로는 대응하지 않음

Laravel LSP는 이러한 “프레임워크 고유의 컨텍스트”를 이해하여, 정확한 자동완성과 진단을 제공합니다.

설치

글로벌 설치

Composer를 사용하여 글로벌로 설치:

composer global require laravel/lsp

Composer의 global bin 디렉터리가 PATH에 포함되어 있는지 확인하고, 다음 명령으로 기동할 수 있습니다:

laravel-lsp

소스로부터의 설치

개발판을 사용하는 경우, 리포지토리를 클론하여 실행할 수 있습니다:

gh repo clone laravel/lsp
cd lsp
composer install
php server

셸 별칭을 설정하여 laravel-lsp 명령을 사용할 수 있도록 합니다:

# Zsh의 경우
echo 'alias laravel-lsp="php /path/to/lsp/server"' >> ~/.zshrc
source ~/.zshrc

# Bash의 경우
echo 'alias laravel-lsp="php /path/to/lsp/server"' >> ~/.bashrc
source ~/.bashrc

에디터별 설정 가이드

Laravel LSP는 표준 LSP 프로토콜을 사용하고 있으므로, LSP를 지원하는 어떤 에디터에서도 동작합니다. 주요 에디터의 설정 방법을 소개합니다.

Sublime Text

LSP 패키지를 설치한 후, Preferences: LSP Settings에서 클라이언트 설정을 추가:

{
    "clients": {
        "laravel-lsp": {
            "enabled": true,
            "command": ["laravel-lsp"],
            "selector": "embedding.php | text.html.blade"
        }
    }
}

Neovim

Neovim 0.11 이상에서는 커스텀 LSP 설정을 직접 추가할 수 있습니다:

vim.lsp.config("laravel_lsp", {
    cmd = { "laravel-lsp" },
    filetypes = { "php", "blade" },
    root_markers = { "artisan", "composer.json", ".git" },
})

vim.lsp.enable("laravel_lsp")

nvim-lspconfig를 사용하는 경우, 다음과 같이 등록:

local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")

if not configs.laravel_lsp then
    configs.laravel_lsp = {
        default_config = {
            cmd = { "laravel-lsp" },
            filetypes = { "php", "blade" },
            root_dir = lspconfig.util.root_pattern("artisan", "composer.json", ".git"),
        },
    }
end

lspconfig.laravel_lsp.setup({})

Cursor

Cursor는 VS Code 확장 기능을 지원하고 있으므로, Laravel 확장 기능이 설치되어 있다면 자동으로 대응합니다. 로컬 개발에는 VS Code 호환 LSP 클라이언트를 사용하고, 명령을 지정:

laravel-lsp

VS Code

VS Code도 마찬가지로 LSP 클라이언트 기능을 가지므로, 확장 기능으로 설정할 수 있습니다.

OpenCode

opencode.json에서 LSP 지원을 활성화하고, Laravel LSP를 커스텀 서버로 설정:

{
    "$schema": "https://opencode.ai/config.json",
    "lsp": {
        "laravel-lsp": {
            "command": ["laravel-lsp"],
            "extensions": [".php", ".blade.php"]
        }
    }
}

GitHub Copilot CLI에서의 설정

GitHub Copilot CLI를 사용하고 있는 경우, ~/.copilot/lsp-config.json에서 글로벌 설정할 수 있습니다. 별도의 에디터 설정은 불필요합니다:

{
  "lspServers": {
    "laravel-lsp": {
      "command": "laravel-lsp",
      "fileExtensions": {
        ".php": "php",
        ".blade.php": "blade"
      }
    }
  }
}

Copilot CLI의 LSP 서버 설정은 initializationOptions에도 대응하고 있으므로, 후술하는 상세 설정을 모두 사용할 수 있습니다.

설정 옵션

LSP 클라이언트는 initializationOptions 경유로 상세 설정을 Laravel LSP에 전달할 수 있습니다.

PHP 환경 검출

phpEnvironment 옵션으로 프로젝트 데이터의 인덱스 작성에 사용할 PHP 명령을 제어합니다. 기본은 auto로 자동 검출:

값	PHP 명령의 동작
`auto`	Herd → Valet → Sail → Lando → DDEV → 로컬 PHP 순으로 검출
`herd`	`herd which-php` 사용
`valet`	`valet which-php` 사용
`sail`	Sail 실행 중일 때 `./vendor/bin/sail php` 사용
`lando`	`lando php` 사용
`ddev`	`ddev php` 사용
`local`	로컬의 PHP 바이너리를 직접 사용

검출에 실패했거나 부정한 값이 전달된 경우에는 php로 폴백합니다.

기본 설정 예

{
    "phpEnvironment": "auto",
    "phpCommand": ["php"],
    "definitionProvider": false
}

기능별 설정

각 기능은 개별적으로 활성/비활성을 전환할 수 있습니다. 접미사는 Completion, Diagnostics, Hover, Link 등:

{
    "routeCompletion": true,
    "routeDiagnostics": true,
    "viewDiagnostics": false,
    "translationHover": true,
    "configLink": true,
    "envCompletion": true,
    "bladeComponentLink": true
}

제공되는 기능 일람

기능 영역	자동완성	호버	진단	링크	퀵 픽스
라우트	✓	✓	✓	✓	-
뷰 & Blade	✓	✓	✓	✓	✓
번역	✓	✓	-	-	-
설정	✓	✓	✓	✓	-
환경 변수	✓	✓	✓	✓	✓
애셋 & Mix	✓	✓	✓	✓	-
Middleware	✓	✓	✓	✓	-
Inertia	✓	-	✓	✓	-
Livewire	✓	✓	-	✓	-
Auth & Policies	✓	✓	✓	✓	-
Container Bindings	✓	✓	✓	✓	-
Validation	✓	-	-	-	-
Controller Actions	✓	-	✓	✓	-
Eloquent	✓	-	-	-	-

퀵 스타트

설치 — composer global require laravel/lsp
에디터 설정 — 위의 에디터별 가이드 참고
Laravel 프로젝트 열기 — 서버가 루트에서 routes, views, translations, config 등의 프로젝트 데이터를 인덱스화합니다
자동완성 사용 — PHP 파일이나 Blade 템플릿 내에서, 프레임워크 인식 자동완성이 자동으로 동작합니다

정리

Laravel LSP는 개발자 경험을 크게 향상시키는 도구입니다. 에디터 표준 기능으로는 대응할 수 없는 프레임워크 고유의 컨텍스트를 이해하여, 보다 정확하고 유익한 자동완성 · 진단을 제공합니다. 필요 요건:

PHP 8.2 이상
Composer
LSP 대응 에디터 (Sublime Text, Neovim, Cursor, VS Code 등)

참고 자료:

​Laravel LSP란

​왜 필요한가

​설치

​글로벌 설치

​소스로부터의 설치

​에디터별 설정 가이드

​Sublime Text

​Neovim

​Cursor

​VS Code

​OpenCode

​GitHub Copilot CLI에서의 설정

​설정 옵션

​PHP 환경 검출

​기본 설정 예

​기능별 설정

​제공되는 기능 일람

​퀵 스타트

​정리

Laravel LSP란

왜 필요한가

설치

글로벌 설치

소스로부터의 설치

에디터별 설정 가이드

Sublime Text

Neovim

Cursor

VS Code

OpenCode

GitHub Copilot CLI에서의 설정

설정 옵션

PHP 환경 검출

기본 설정 예

기능별 설정

제공되는 기능 일람

퀵 스타트

정리