> ## 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 신규 코드 해석 에코시스템 — surveyor / ranger / roster

> Laravel이 공개한 정적 해석 에코시스템을 구성하는 세 패키지(surveyor · ranger · roster)를 소개합니다. PHP 코드 해석부터 패키지 검출까지, 패키지 개발자 · 도구 작성자가 알아 두어야 할 신규 도구군을 설명합니다.

<Info>
  이 글은 GitHub 리포지토리의 README와 소스 코드에 기반한 정보입니다. 세 패키지는 모두 정식 릴리스 전의 Beta 버전입니다 (2026년 4월 시점).
</Info>

<Warning>
  surveyor · ranger · roster는 모두 **Beta 릴리스 중**입니다. v1.0.0 릴리스 전에 API가 변경될 가능성이 있습니다. 프로덕션 환경에서의 이용은 신중히 판단해 주세요.
</Warning>

## 최신 릴리스 상황 (2026년 4월)

| 패키지                | 최신 릴리스    | 보충                                                                                                           |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------ |
| `laravel/roster`   | `v0.5.1`  | `laravel/boost`의 `composer.json`에서 `^0.5.0`이 요구되며, `BoostServiceProvider`에서 `Roster::scan(base_path())`가 실행됨 |
| `laravel/ranger`   | `v0.1.12` | `composer.json`에서 `laravel/surveyor:^0.1.0`에 의존                                                              |
| `laravel/surveyor` | `v0.1.9`  | `ranger`의 해석 기반으로서 이용되는 저레이어                                                                                 |

## 개요

Laravel은 2026년에 들어서 코드 해석에 관련된 세 패키지를 공개했습니다. 이것들은 단독으로도 사용할 수 있지만, 상호 연동하는 **코드 해석 에코시스템**을 형성하고 있습니다.

```mermaid theme={null}
graph TD
    A["laravel/roster<br>패키지 검출"] --> B["laravel/ranger<br>고레벨 인트로스펙션"]
    B --> C["laravel/surveyor<br>저레벨 정적 해석 엔진"]
    D["Boost<br>AI 개발 지원 도구"] --> A
    E["도구 · 패키지 개발자"] --> A
    E --> B
    E --> C
```

| 패키지                | 역할                   | 설치                                      |
| ------------------ | -------------------- | --------------------------------------- |
| `laravel/surveyor` | PHP 코드의 정적 해석 엔진     | `composer require laravel/surveyor`     |
| `laravel/ranger`   | Laravel 앱 전체의 인트로스펙션 | `composer require laravel/ranger`       |
| `laravel/roster`   | 에코시스템 패키지 검출         | `composer require laravel/roster --dev` |

각 패키지의 세부 내용을 순서대로 살펴보겠습니다.

***

## laravel/surveyor — 정적 해석 엔진

[laravel/surveyor](https://github.com/laravel/surveyor)는 PHP 파일을 파싱하여 클래스 · 메서드 · 프로퍼티 · 반환 값의 타입 등의 상세한 메타 정보를 구조화된 형식으로 제공하는 정적 해석 도구입니다. 다른 도구나 패키지가 이용할 수 있는 형태로 정보를 추출하는 것에 특화되어 있습니다.

### 설치

```bash theme={null}
composer require laravel/surveyor
```

### 기본 사용법

#### 파일 해석

```php theme={null}
use Laravel\Surveyor\Analyzer\Analyzer;

$analyzer = app(Analyzer::class);

// 파일 경로로 해석
$result = $analyzer->analyze('/path/to/your/File.php');

// 해석된 스코프에 액세스
$scope = $result->analyzed();

// 클래스 결과에 액세스
$classResult = $result->result();
```

#### 클래스를 직접 해석

```php theme={null}
$result = $analyzer->analyzeClass(\App\Models\User::class);
$classResult = $result->result();
```

### ClassResult에서 얻을 수 있는 정보

```php theme={null}
$classResult = $analyzer->analyzeClass(App\Models\User::class)->result();

// 클래스 정보
$name = $classResult->name();            // 'App\Models\User'
$namespace = $classResult->namespace();  // 'App\Models'
$filePath = $classResult->filePath();

// 상속 관계
$extends = $classResult->extends();
$implements = $classResult->implements();

// 메서드 정보
$method = $classResult->getMethod('store');
$returnType = $method->returnType();
$parameters = $method->parameters();
$rules = $method->validationRules(); // 유효성 검증 룰도 취득 가능

// 프로퍼티 정보
$property = $classResult->getProperty('email');
$type = $property->type;
$visibility = $property->visibility; // 'public', 'protected', 'private'

// 공개 메서드 · 프로퍼티 일람
$publicMethods = $classResult->publicMethods();
$publicProperties = $classResult->publicProperties();
```

### 타입 시스템

Surveyor는 충실한 타입 시스템을 가지고 있어, PHP의 타입을 구조화하여 다룰 수 있습니다.

```php theme={null}
use Laravel\Surveyor\Types\Type;

// 각종 타입 생성
$stringType = Type::string();
$intType = Type::int();
$boolType = Type::bool();
$nullType = Type::null();

// 유니온 타입 (string|null 등)
$unionType = Type::union(Type::string(), Type::null());

// 타입 판정
use Laravel\Surveyor\Types\StringType;

if (Type::is($returnType, StringType::class)) {
    // 문자열 타입 처리
}
```

### 캐시 설정

해석 결과를 캐시하여 반복 실행의 퍼포먼스를 개선할 수 있습니다.

```php theme={null}
use Laravel\Surveyor\Analyzer\AnalyzedCache;

// 디스크 캐시 활성화
AnalyzedCache::enableDiskCache(storage_path('surveyor-cache'));

// 캐시 클리어
AnalyzedCache::clear();
```

환경 변수로도 설정할 수 있습니다.

```env theme={null}
SURVEYOR_CACHE_ENABLED=true
SURVEYOR_CACHE_DIR=/path/to/cache
```

### Eloquent 모델 해석

Surveyor는 데이터베이스에 접속을 시도하여 Eloquent 모델을 특별히 해석합니다. 모델의 릴레이션 · 속성 · 접근자 · 캐스트도 검출됩니다.

```php theme={null}
$result = $analyzer->analyzeClass(App\Models\User::class)->result();

// 데이터베이스 속성이 자동 검출됨
$emailProperty = $result->getProperty('email');

// 릴레이션 메서드 판정
$method = $result->getMethod('posts');
if ($method->isModelRelation()) {
    // 이 메서드는 릴레이션
}
```

<Info>
  Surveyor는 Eloquent 모델 해석 시 데이터베이스에 접속을 시도하므로, 완전한 정적 해석이 아닙니다. 또한 퍼포먼스와 메모리 사용량은 현재 개선 중이며, 컨트리뷰션을 환영합니다.
</Info>

***

## laravel/ranger — 고레벨 인트로스펙션

[laravel/ranger](https://github.com/laravel/ranger)는 surveyor를 래핑하여, Laravel 애플리케이션 전체를 워크스루하며 라우트 · 모델 · Enum · 브로드캐스트 이벤트 · 환경 변수 · Inertia 컴포넌트 등의 정보를 수집하는 고레벨 라이브러리입니다.

### 설치

```bash theme={null}
composer require laravel/ranger
```

### 기본 사용법

콜백 형식으로, 각 컴포넌트가 발견되었을 때의 처리를 기술합니다.

```php theme={null}
use Laravel\Ranger\Ranger;
use Laravel\Ranger\Components;
use Illuminate\Support\Collection;

$ranger = app(Ranger::class);

// 라우트가 발견될 때마다 호출
$ranger->onRoute(function (Components\Route $route) {
    echo $route->uri();
});

// 모델이 발견될 때마다 호출
$ranger->onModel(function (Components\Model $model) {
    foreach ($model->getAttributes() as $name => $type) {
        // 속성명과 타입 처리
    }
});

// Enum이 발견될 때마다 호출
$ranger->onEnum(function (Components\Enum $enum) {
    //
});

// 브로드캐스트 이벤트가 발견될 때마다 호출
$ranger->onBroadcastEvent(function (Components\BroadcastEvent $event) {
    //
});

// 모든 라우트가 수집된 후 한 번만 호출
$ranger->onRoutes(function (Collection $routes) {
    //
});

// 모든 모델이 수집된 후 한 번만 호출
$ranger->onModels(function (Collection $models) {
    //
});

// 애플리케이션 전체를 워크스루하여 콜백 발화
$ranger->walk();
```

### Ranger가 수집하는 컴포넌트

| 컬렉터                      | 설명                                                      |
| ------------------------ | ------------------------------------------------------- |
| **Routes**               | 전 등록 라우트 (URI · 파라미터 · HTTP 메서드 · 컨트롤러 · 유효성 검증 룰 · 응답) |
| **Models**               | Eloquent 모델과 속성 · 타입 · 릴레이션                             |
| **Enums**                | PHP의 Backed Enum (정수 · 문자열을 가진 Enum)과 케이스 · 값           |
| **BroadcastEvents**      | `ShouldBroadcast`를 구현한 이벤트와 페이로드                        |
| **BroadcastChannels**    | 등록된 브로드캐스트 채널                                           |
| **EnvironmentVariables** | `.env` 파일에서 정의된 환경 변수                                   |
| **Inertia Shared Data**  | 전역으로 공유된 Inertia.js props                               |
| **Inertia Components**   | Inertia.js의 페이지 컴포넌트와 기대되는 props                        |

***

## laravel/roster — 패키지 검출 도구

[laravel/roster](https://github.com/laravel/roster)는 프로젝트에 어떤 Laravel 에코시스템 패키지가 설치되어 있는지를 검출하는 도구입니다. 패키지 개발자나 도구 작성자가 "이 프로젝트는 Inertia를 사용하고 있는가?", "Livewire의 버전은?"과 같은 정보를 간단히 얻을 수 있습니다.

### 설치

```bash theme={null}
composer require laravel/roster --dev
```

### 기본 사용법

```php theme={null}
use Laravel\Roster\Roster;
use Laravel\Roster\Packages;

// 디렉터리를 스캔하여 Roster 취득
$roster = Roster::scan($directory);

// 설치된 패키지 목록
$roster->packages();

// 프로덕션용 패키지만
$roster->packages()->production();

// 개발 전용 패키지만
$roster->packages()->dev();

// 특정 패키지의 유무 확인
$roster->uses(Packages::INERTIA);        // bool
$roster->uses(Packages::LIVEWIRE);       // bool

// 버전 조건 지정 확인
$roster->usesVersion(Packages::INERTIA, '2.0.0', '>=');   // Inertia 2.0.0 이상인가?
$roster->usesVersion(Packages::LIVEWIRE, '3.0.0', '>=');  // Livewire 3.0.0 이상인가?

// JavaScript 패키지 매니저 검출
$packageManager = $roster->nodePackageManager(); // 'npm', 'yarn', 'bun' 등
```

***

## 실제 유스케이스

### AI 가이드라인 생성 도구 (Boost)

[Laravel Boost](https://github.com/laravel/boost)는 roster를 사용하여 설치된 패키지 구성을 파악하고, AI 에이전트(GitHub Copilot이나 Claude 등)용의 가이드라인과 스킬의 생성을 자동 조정합니다. "이 프로젝트는 Inertia를 사용하고 있는가?", "Livewire는 들어 있는가?"라는 정보를 바탕으로, 적절한 가이드라인 파일을 선택하여 AI 에이전트에 제공합니다.

```mermaid theme={null}
sequenceDiagram
    participant Boost as Laravel Boost
    participant Roster as laravel/roster
    participant AI as AI 에이전트
    Boost->>Roster: Roster::scan(base_path())
    Roster->>Boost: packages() [Inertia, Livewire, Pint...]
    Boost->>Boost: 패키지별 가이드라인 선택
    Boost->>AI: Inertia 가이드라인, Livewire 가이드라인...
```

### 패키지 호환성 체커 만들기

사용자의 프로젝트에 설치된 패키지에 따라 동작을 바꾸는 패키지를 개발할 경우, roster가 매우 유용합니다.

```php theme={null}
use Laravel\Roster\Roster;
use Laravel\Roster\Packages;

$roster = Roster::scan(base_path());

if ($roster->uses(Packages::INERTIA)) {
    // Inertia용 처리
    if ($roster->usesVersion(Packages::INERTIA, '2.0.0', '>=')) {
        // Inertia v2 이상용 처리
    }
}

if ($roster->uses(Packages::LIVEWIRE)) {
    // Livewire용 처리
}

// JavaScript 패키지 매니저에 따라 설치 명령을 바꾸기
$pm = $roster->nodePackageManager();
echo "Run: {$pm} install your-package";
```

### 애플리케이션 문서 자동 생성

ranger를 사용하면 Laravel 앱의 라우트 · 모델 · Enum을 자동으로 수집하여 문서를 생성하는 도구를 구축할 수 있습니다.

```php theme={null}
use Laravel\Ranger\Ranger;
use Laravel\Ranger\Components;

$ranger = app(Ranger::class);
$docs = [];

$ranger->onRoute(function (Components\Route $route) use (&$docs) {
    $docs['routes'][] = [
        'uri' => $route->uri(),
        // 라우트의 유효성 검증 룰 · 응답 타입 등도 취득 가능
    ];
});

$ranger->onModel(function (Components\Model $model) use (&$docs) {
    $docs['models'][] = [
        'attributes' => $model->getAttributes(),
    ];
});

$ranger->walk();

// $docs에 앱 전체의 구조 정보가 수집됨
```

***

## 정리

surveyor · ranger · roster는 Laravel 에코시스템에서의 **프로그램에 의한 코드 해석**의 새로운 기반을 제공합니다.

```mermaid theme={null}
graph LR
    A["surveyor<br>PHP 파일을 파싱<br>클래스 · 메서드 · 타입 추출"] --> B["ranger<br>Laravel 앱 전체를 주사<br>라우트 · 모델 · Enum 수집"]
    B --> C["roster<br>설치된 패키지 검출<br>버전 · 종류 확인"]
```

이 패키지들은 주로 패키지 개발자 · 도구 작성자를 대상으로 하고 있으며, 최종 사용자가 직접 사용하는 것은 아닙니다. 하지만 Laravel Boost처럼 Laravel 공식 도구의 내부에서도 적극적으로 활용되고 있으며, 향후 에코시스템 확대가 기대됩니다.

<Columns cols={3}>
  <Card title="laravel/surveyor" icon="github" href="https://github.com/laravel/surveyor">
    PHP 코드의 정적 해석 엔진
  </Card>

  <Card title="laravel/ranger" icon="github" href="https://github.com/laravel/ranger">
    고레벨 인트로스펙션 라이브러리
  </Card>

  <Card title="laravel/roster" icon="github" href="https://github.com/laravel/roster">
    패키지 검출 도구
  </Card>
</Columns>


## Related topics

- [2026년 4월 Laravel 업데이트](/ko/blog/changelog/202604.md)
- [laravel/agent-skills — Laravel 공식 AI 에이전트 스킬 모음](/ko/blog/agent-skills-introduction.md)
- [Laravel과 AI 개발](/ko/ai.md)
- [Laravel Boost](/ko/boost.md)
- [2026년 3월 Laravel 업데이트](/ko/blog/changelog/202603.md)