> ## 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's new code analysis ecosystem — surveyor / ranger / roster

> An introduction to the three packages that make up Laravel's newly published static analysis ecosystem: surveyor, ranger, and roster. A guide to the new tools that package developers and tool authors should know about—from PHP code analysis to package detection.

<Info>
  This article is based on the GitHub repository READMEs and source code. All three packages are still in Beta ahead of a formal release (as of April 2026).
</Info>

<Warning>
  surveyor, ranger, and roster are all **in Beta**. APIs may change before v1.0.0 is released. Use in production with caution.
</Warning>

## Latest release status (April 2026)

| Package            | Latest release | Notes                                                                                                                 |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `laravel/roster`   | `v0.5.1`       | `laravel/boost`'s `composer.json` requires `^0.5.0`, and its `BoostServiceProvider` calls `Roster::scan(base_path())` |
| `laravel/ranger`   | `v0.1.12`      | Depends on `laravel/surveyor:^0.1.0` in `composer.json`                                                               |
| `laravel/surveyor` | `v0.1.9`       | The lower-layer analysis foundation used by `ranger`                                                                  |

## Overview

Entering 2026, Laravel has published three packages related to code analysis. Each can be used on its own, but together they form a **code analysis ecosystem**.

```mermaid theme={null}
graph TD
    A["laravel/roster<br>package detection"] --> B["laravel/ranger<br>high-level introspection"]
    B --> C["laravel/surveyor<br>low-level static analysis engine"]
    D["Boost<br>AI development assistant"] --> A
    E["Tool and package developers"] --> A
    E --> B
    E --> C
```

| Package            | Role                                        | Installation                            |
| ------------------ | ------------------------------------------- | --------------------------------------- |
| `laravel/surveyor` | Static analysis engine for PHP code         | `composer require laravel/surveyor`     |
| `laravel/ranger`   | Introspection across the entire Laravel app | `composer require laravel/ranger`       |
| `laravel/roster`   | Ecosystem package detection                 | `composer require laravel/roster --dev` |

Let's look at each package in detail.

***

## laravel/surveyor — the static analysis engine

[laravel/surveyor](https://github.com/laravel/surveyor) is a static analysis tool that parses PHP files and provides detailed metadata about classes, methods, properties, return types, and more in a structured form. It's specialized in extracting information in a form other tools and packages can consume.

### Installation

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

### Basic usage

#### Analyze a file

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

$analyzer = app(Analyzer::class);

// Analyze by file path
$result = $analyzer->analyze('/path/to/your/File.php');

// Access the analyzed scope
$scope = $result->analyzed();

// Access the class result
$classResult = $result->result();
```

#### Analyze a class directly

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

### Information available from ClassResult

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

// Class info
$name = $classResult->name();            // 'App\Models\User'
$namespace = $classResult->namespace();  // 'App\Models'
$filePath = $classResult->filePath();

// Inheritance
$extends = $classResult->extends();
$implements = $classResult->implements();

// Method info
$method = $classResult->getMethod('store');
$returnType = $method->returnType();
$parameters = $method->parameters();
$rules = $method->validationRules(); // Validation rules are also available

// Property info
$property = $classResult->getProperty('email');
$type = $property->type;
$visibility = $property->visibility; // 'public', 'protected', 'private'

// Lists of public methods and properties
$publicMethods = $classResult->publicMethods();
$publicProperties = $classResult->publicProperties();
```

### Type system

Surveyor has a rich type system that structures PHP types.

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

// Creating various types
$stringType = Type::string();
$intType = Type::int();
$boolType = Type::bool();
$nullType = Type::null();

// Union type (e.g. string|null)
$unionType = Type::union(Type::string(), Type::null());

// Type checks
use Laravel\Surveyor\Types\StringType;

if (Type::is($returnType, StringType::class)) {
    // Handle string type
}
```

### Cache configuration

You can cache analysis results to improve performance on repeated runs.

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

// Enable disk cache
AnalyzedCache::enableDiskCache(storage_path('surveyor-cache'));

// Clear the cache
AnalyzedCache::clear();
```

It can also be configured via environment variables.

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

### Eloquent model analysis

Surveyor treats Eloquent models specially by trying to connect to the database. Model relationships, attributes, accessors, and casts are also detected.

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

// Database attributes are auto-detected
$emailProperty = $result->getProperty('email');

// Identify relationship methods
$method = $result->getMethod('posts');
if ($method->isModelRelation()) {
    // This method is a relationship
}
```

<Info>
  Because Surveyor attempts to connect to the database when analyzing Eloquent models, it's not purely static analysis. Performance and memory usage are also under active improvement, and contributions are welcome.
</Info>

***

## laravel/ranger — high-level introspection

[laravel/ranger](https://github.com/laravel/ranger) wraps surveyor to provide a high-level library that walks through your entire Laravel application and collects information on routes, models, enums, broadcast events, environment variables, Inertia components, and more.

### Installation

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

### Basic usage

Use callbacks to describe what should happen when each component is discovered.

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

$ranger = app(Ranger::class);

// Called every time a route is discovered
$ranger->onRoute(function (Components\Route $route) {
    echo $route->uri();
});

// Called every time a model is discovered
$ranger->onModel(function (Components\Model $model) {
    foreach ($model->getAttributes() as $name => $type) {
        // Handle attribute name and type
    }
});

// Called every time an enum is discovered
$ranger->onEnum(function (Components\Enum $enum) {
    //
});

// Called every time a broadcast event is discovered
$ranger->onBroadcastEvent(function (Components\BroadcastEvent $event) {
    //
});

// Called once after all routes are collected
$ranger->onRoutes(function (Collection $routes) {
    //
});

// Called once after all models are collected
$ranger->onModels(function (Collection $models) {
    //
});

// Walk the entire application and fire callbacks
$ranger->walk();
```

### Components Ranger collects

| Collector                | Description                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| **Routes**               | All registered routes (URI, parameters, HTTP methods, controller, validation rules, responses) |
| **Models**               | Eloquent models with attributes, types, and relationships                                      |
| **Enums**                | PHP Backed Enums (with integer or string values) and their cases and values                    |
| **BroadcastEvents**      | Events implementing `ShouldBroadcast` with their payloads                                      |
| **BroadcastChannels**    | Registered broadcast channels                                                                  |
| **EnvironmentVariables** | Environment variables defined in `.env`                                                        |
| **Inertia Shared Data**  | Globally shared Inertia.js props                                                               |
| **Inertia Components**   | Inertia.js page components and their expected props                                            |

***

## laravel/roster — a package detection tool

[laravel/roster](https://github.com/laravel/roster) is a tool that detects which Laravel ecosystem packages are installed in a project. Package developers and tool authors can easily answer questions like "does this project use Inertia?" and "which Livewire version is installed?"

### Installation

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

### Basic usage

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

// Scan a directory and obtain a Roster instance
$roster = Roster::scan($directory);

// List installed packages
$roster->packages();

// Production packages only
$roster->packages()->production();

// Dev-only packages
$roster->packages()->dev();

// Check for a specific package
$roster->uses(Packages::INERTIA);        // bool
$roster->uses(Packages::LIVEWIRE);       // bool

// Check with a version constraint
$roster->usesVersion(Packages::INERTIA, '2.0.0', '>=');   // Inertia 2.0.0+?
$roster->usesVersion(Packages::LIVEWIRE, '3.0.0', '>=');  // Livewire 3.0.0+?

// Detect the JavaScript package manager
$packageManager = $roster->nodePackageManager(); // 'npm', 'yarn', 'bun', etc.
```

***

## Real-world use cases

### AI guideline generation tool (Boost)

[Laravel Boost](https://github.com/laravel/boost) uses roster to understand the installed package layout and automatically tune the guidelines and skills it generates for AI agents (like GitHub Copilot and Claude). Based on facts such as "does this project use Inertia?" and "is Livewire installed?", it selects the appropriate guideline files and supplies them to the AI agent.

```mermaid theme={null}
sequenceDiagram
    participant Boost as Laravel Boost
    participant Roster as laravel/roster
    participant AI as AI agent
    Boost->>Roster: Roster::scan(base_path())
    Roster->>Boost: packages() [Inertia, Livewire, Pint...]
    Boost->>Boost: Select per-package guidelines
    Boost->>AI: Inertia guidelines, Livewire guidelines...
```

### Building a package compatibility checker

If you're developing a package that behaves differently depending on which packages are installed in the user's project, roster is very useful.

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

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

if ($roster->uses(Packages::INERTIA)) {
    // Inertia-specific behavior
    if ($roster->usesVersion(Packages::INERTIA, '2.0.0', '>=')) {
        // Inertia v2+ behavior
    }
}

if ($roster->uses(Packages::LIVEWIRE)) {
    // Livewire-specific behavior
}

// Choose install commands based on the JavaScript package manager
$pm = $roster->nodePackageManager();
echo "Run: {$pm} install your-package";
```

### Automatic application documentation generation

With ranger, you can build a tool that automatically collects routes, models, and enums from a Laravel app and generates documentation.

```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(),
        // Route validation rules and response types are also available
    ];
});

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

$ranger->walk();

// $docs now contains structural information for the entire app
```

***

## Summary

surveyor, ranger, and roster provide a new foundation for **programmatic code analysis** in the Laravel ecosystem.

```mermaid theme={null}
graph LR
    A["surveyor<br>Parse PHP files<br>Extract classes, methods, types"] --> B["ranger<br>Walk the whole Laravel app<br>Collect routes, models, enums"]
    B --> C["roster<br>Detect installed packages<br>Check versions and types"]
```

These packages are aimed primarily at package developers and tool authors—they aren't intended for direct use by end users. Even so, they're actively used inside official Laravel tools like Laravel Boost, and ecosystem adoption is expected to grow.

<Columns cols={3}>
  <Card title="laravel/surveyor" icon="github" href="https://github.com/laravel/surveyor">
    Static analysis engine for PHP code
  </Card>

  <Card title="laravel/ranger" icon="github" href="https://github.com/laravel/ranger">
    High-level introspection library
  </Card>

  <Card title="laravel/roster" icon="github" href="https://github.com/laravel/roster">
    Package detection tool
  </Card>
</Columns>


## Related topics

- [Laravel and AI development](/en/ai.md)
- [Package Static Analysis (PHPStan / Larastan)](/en/advanced/package-static-analysis.md)
- [Laravel Package Skeleton — the official starter template for packages](/en/blog/package-skeleton-introduction.md)
- [April 2026 Laravel updates](/en/blog/changelog/202604.md)
- [laravel/agent-skills — Laravel's official AI agent skills](/en/blog/agent-skills-introduction.md)