> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Laravel 공식 Language Server Protocol 구현. 에디터에 프레임워크 인식 자동완성과 호버 기능을 제공.

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

## Laravel LSP란

**Laravel LSP** (Language Server Protocol)는 Laravel 프레임워크를 인식한 IDE 기능을 에디터에 제공하는 공식 도구입니다. [Language Server Protocol](https://microsoft.github.io/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를 사용하여 글로벌로 설치:

```bash theme={null}
composer global require laravel/lsp
```

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

```bash theme={null}
laravel-lsp
```

### 소스로부터의 설치

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

```bash theme={null}
gh repo clone laravel/lsp
cd lsp
composer install
php server
```

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

```bash theme={null}
# 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 패키지](https://packagecontrol.io/packages/LSP)를 설치한 후, `Preferences: LSP Settings`에서 클라이언트 설정을 추가:

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

### Neovim

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

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

vim.lsp.enable("laravel_lsp")
```

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

```lua theme={null}
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 클라이언트를 사용하고, 명령을 지정:

```sh theme={null}
laravel-lsp
```

### VS Code

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

### OpenCode

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

```json theme={null}
{
    "$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`에서 글로벌 설정할 수 있습니다. 별도의 에디터 설정은 불필요합니다:

```json theme={null}
{
  "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`로 폴백합니다.

### 기본 설정 예

```json theme={null}
{
    "phpEnvironment": "auto",
    "phpCommand": ["php"],
    "definitionProvider": false
}
```

### 기능별 설정

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

```json theme={null}
{
    "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           | ✓    | -  | -  | -  | -    |

## 퀵 스타트

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

## 정리

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

**필요 요건:**

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

**참고 자료:**

* [Laravel LSP GitHub 리포지토리](https://github.com/laravel/lsp)
* [Language Server Protocol 공식](https://microsoft.github.io/language-server-protocol/)
* [GitHub Copilot CLI LSP 설정 가이드](https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers)


## Related topics

- [Vite에 의한 에셋 번들](/ko/vite.md)
- [Laravel Socialite (소셜 인증)](/ko/socialite.md)
- [Laravel 13 신기능 정리](/ko/blog/laravel-13-new-features.md)
- [Plugin Directories](/ko/packages/laravel-copilot-sdk/plugin-directories.md)
- [Laravel Cloud Hibernation (자동 휴면)](/ko/blog/laravel-cloud-hibernation.md)