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

이 기사는 v0.0.27, 2026년 7월 시점의 정보입니다. Packagist에 등록되어 composer global require laravel/lsp로 설치할 수 있게 되었습니다.

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

공식 Laravel Sublime Text extension을 설치하여 설정합니다.

Zed

공식 Laravel Zed extension을 설치하여 설정합니다.

VS Code

공식 Laravel VS Code extension을 설치하여 설정합니다.

Cursor

Cursor는 VS Code 확장 기능에 대응하므로 위의 Laravel VS Code extension을 그대로 사용할 수 있습니다.

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({})

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
}

Pest 헬퍼 문서 블록

v0.0.27에서 추가된 옵션입니다. Pest의 테스트나 Composer autoload 파일이 변경되었을 때 Pest 헬퍼용 docblock을 자동 생성·업데이트합니다:

옵션	타입	기본값	설명
`pestGenerateDocBlocks`	`boolean`	`true`	Pest 헬퍼의 docblock을 생성하고 계속 업데이트할지
`pestHelperFilePath`	`string`	`"storage/framework/testing/_pest.php"`	Pest 헬퍼 출력 경로(프로젝트 루트로부터의 상대 경로)

{
    "pestGenerateDocBlocks": true,
    "pestHelperFilePath": "storage/framework/testing/_pest.php"
}

기능별 설정

각 기능은 개별로 활성화/비활성화를 전환할 수 있습니다. 접미사는 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 등)

참고 자료:

Changelog

Laravel 13

제품

패키지 소개

신규 리포지토리 조사

업그레이드 가이드

인증

프런트엔드

환경 구축

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

Laravel LSP란

왜 필요한가

설치

전역 설치

소스로부터 설치

에디터별 설정 가이드

Sublime Text

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI에서의 설정

설정 옵션

PHP 환경 감지

기본 설정 예

Pest 헬퍼 문서 블록

기능별 설정

제공되는 기능 일람

퀵스타트

정리

​Laravel LSP란

​왜 필요한가

​설치

​전역 설치

​소스로부터 설치

​에디터별 설정 가이드

​Sublime Text

​Zed

​VS Code

​Cursor

​Neovim

​OpenCode

​GitHub Copilot CLI에서의 설정

​설정 옵션

​PHP 환경 감지

​기본 설정 예

​Pest 헬퍼 문서 블록

​기능별 설정

​제공되는 기능 일람

​퀵스타트

​정리

Laravel LSP란

왜 필요한가

설치

전역 설치

소스로부터 설치

에디터별 설정 가이드

Sublime Text

Zed

VS Code

Cursor

Neovim

OpenCode

GitHub Copilot CLI에서의 설정

설정 옵션

PHP 환경 감지

기본 설정 예

Pest 헬퍼 문서 블록

기능별 설정

제공되는 기능 일람

퀵스타트

정리