Laravel 신규 코드 해석 에코시스템 — surveyor / ranger / roster

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

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

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

​

최신 릴리스 상황 (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년에 들어서 코드 해석에 관련된 세 패키지를 공개했습니다. 이것들은 단독으로도 사용할 수 있지만, 상호 연동하는 코드 해석 에코시스템을 형성하고 있습니다.

패키지	역할	설치
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는 PHP 파일을 파싱하여 클래스 · 메서드 · 프로퍼티 · 반환 값의 타입 등의 상세한 메타 정보를 구조화된 형식으로 제공하는 정적 해석 도구입니다. 다른 도구나 패키지가 이용할 수 있는 형태로 정보를 추출하는 것에 특화되어 있습니다.

​

설치

composer require laravel/surveyor

​

기본 사용법

​

파일 해석

use Laravel\Surveyor\Analyzer\Analyzer;

$analyzer = app(Analyzer::class);

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

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

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

​

클래스를 직접 해석

$result = $analyzer->analyzeClass(\App\Models\User::class);
$classResult = $result->result();

​

ClassResult에서 얻을 수 있는 정보

$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의 타입을 구조화하여 다룰 수 있습니다.

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)) {
    // 문자열 타입 처리
}

​

캐시 설정

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

use Laravel\Surveyor\Analyzer\AnalyzedCache;

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

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

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

SURVEYOR_CACHE_ENABLED=true
SURVEYOR_CACHE_DIR=/path/to/cache

​

Eloquent 모델 해석

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

$result = $analyzer->analyzeClass(App\Models\User::class)->result();

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

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

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

---

​

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

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

​

설치

composer require laravel/ranger

​

기본 사용법

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

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는 프로젝트에 어떤 Laravel 에코시스템 패키지가 설치되어 있는지를 검출하는 도구입니다. 패키지 개발자나 도구 작성자가 “이 프로젝트는 Inertia를 사용하고 있는가?”, “Livewire의 버전은?”과 같은 정보를 간단히 얻을 수 있습니다.

​

설치

composer require laravel/roster --dev

​

기본 사용법

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는 roster를 사용하여 설치된 패키지 구성을 파악하고, AI 에이전트(GitHub Copilot이나 Claude 등)용의 가이드라인과 스킬의 생성을 자동 조정합니다. “이 프로젝트는 Inertia를 사용하고 있는가?”, “Livewire는 들어 있는가?”라는 정보를 바탕으로, 적절한 가이드라인 파일을 선택하여 AI 에이전트에 제공합니다.

​

패키지 호환성 체커 만들기

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

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을 자동으로 수집하여 문서를 생성하는 도구를 구축할 수 있습니다.

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 에코시스템에서의 프로그램에 의한 코드 해석의 새로운 기반을 제공합니다.

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

laravel/surveyor

PHP 코드의 정적 해석 엔진

laravel/ranger

고레벨 인트로스펙션 라이브러리

laravel/roster

패키지 검출 도구