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

# Nuevo ecosistema de análisis de código de Laravel — surveyor / ranger / roster

> Presentamos los tres paquetes (surveyor, ranger y roster) que componen el ecosistema de análisis estático publicado por Laravel. Se explican estas nuevas herramientas que deben conocer los desarrolladores de paquetes y autores de herramientas, desde el análisis de código PHP hasta la detección de paquetes.

<Info>
  Este artículo se basa en los README y el código fuente de los repositorios de GitHub. Los tres paquetes se encuentran en versión Beta previa al lanzamiento oficial (a fecha de abril de 2026).
</Info>

<Warning>
  surveyor, ranger y roster están todos en **release Beta**. La API puede cambiar antes del lanzamiento de v1.0.0. Evalúa con cautela su uso en producción.
</Warning>

## Estado de la última release (abril de 2026)

| Paquete            | Última release | Nota                                                                                                                        |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `laravel/roster`   | `v0.5.1`       | El `composer.json` de `laravel/boost` requiere `^0.5.0`, y en `BoostServiceProvider` se ejecuta `Roster::scan(base_path())` |
| `laravel/ranger`   | `v0.1.12`      | Depende de `laravel/surveyor:^0.1.0` en su `composer.json`                                                                  |
| `laravel/surveyor` | `v0.1.9`       | Capa de bajo nivel que sirve de base de análisis para `ranger`                                                              |

## Descripción general

Entrado 2026, Laravel ha publicado tres paquetes relacionados con el análisis de código. Se pueden usar de forma independiente, pero forman un **ecosistema de análisis de código** que se integra entre sí.

```mermaid theme={null}
graph TD
    A["laravel/roster<br>Detección de paquetes"] --> B["laravel/ranger<br>Introspección de alto nivel"]
    B --> C["laravel/surveyor<br>Motor de análisis estático de bajo nivel"]
    D["Boost<br>Herramienta de asistencia con IA"] --> A
    E["Desarrolladores de herramientas y paquetes"] --> A
    E --> B
    E --> C
```

| Paquete            | Rol                                      | Instalación                             |
| ------------------ | ---------------------------------------- | --------------------------------------- |
| `laravel/surveyor` | Motor de análisis estático de código PHP | `composer require laravel/surveyor`     |
| `laravel/ranger`   | Introspección global de una app Laravel  | `composer require laravel/ranger`       |
| `laravel/roster`   | Detección de paquetes del ecosistema     | `composer require laravel/roster --dev` |

Veamos los detalles de cada paquete uno a uno.

***

## laravel/surveyor — Motor de análisis estático

[laravel/surveyor](https://github.com/laravel/surveyor) es una herramienta de análisis estático que parsea archivos PHP y ofrece en formato estructurado meta-información detallada de clases, métodos, propiedades y tipos de retorno. Está especializada en extraer información en un formato utilizable por otras herramientas y paquetes.

### Instalación

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

### Uso básico

#### Analizar un archivo

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

$analyzer = app(Analyzer::class);

// Análisis por ruta de archivo
$result = $analyzer->analyze('/path/to/your/File.php');

// Acceder al scope analizado
$scope = $result->analyzed();

// Acceder al resultado de clase
$classResult = $result->result();
```

#### Analizar una clase directamente

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

### Información obtenible con ClassResult

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

// Información de la clase
$name = $classResult->name();            // 'App\Models\User'
$namespace = $classResult->namespace();  // 'App\Models'
$filePath = $classResult->filePath();

// Relaciones de herencia
$extends = $classResult->extends();
$implements = $classResult->implements();

// Información de método
$method = $classResult->getMethod('store');
$returnType = $method->returnType();
$parameters = $method->parameters();
$rules = $method->validationRules(); // También se pueden obtener las reglas de validación

// Información de propiedad
$property = $classResult->getProperty('email');
$type = $property->type;
$visibility = $property->visibility; // 'public', 'protected', 'private'

// Listado de métodos y propiedades públicas
$publicMethods = $classResult->publicMethods();
$publicProperties = $classResult->publicProperties();
```

### Sistema de tipos

Surveyor cuenta con un sistema de tipos completo que permite tratar los tipos de PHP de forma estructurada.

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

// Generación de distintos tipos
$stringType = Type::string();
$intType = Type::int();
$boolType = Type::bool();
$nullType = Type::null();

// Tipos unión (string|null, etc.)
$unionType = Type::union(Type::string(), Type::null());

// Comprobación de tipo
use Laravel\Surveyor\Types\StringType;

if (Type::is($returnType, StringType::class)) {
    // Procesamiento del tipo string
}
```

### Configuración de caché

Puedes cachear los resultados del análisis para mejorar el rendimiento de ejecuciones repetidas.

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

// Activar caché en disco
AnalyzedCache::enableDiskCache(storage_path('surveyor-cache'));

// Limpiar la caché
AnalyzedCache::clear();
```

También se puede configurar mediante variables de entorno.

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

### Análisis de modelos Eloquent

Surveyor intenta conectarse a la base de datos y analiza los modelos Eloquent de forma especial. Detecta relaciones, atributos, accesores y casts de los modelos.

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

// Los atributos de base de datos se detectan automáticamente
$emailProperty = $result->getProperty('email');

// Determinar métodos de relación
$method = $result->getMethod('posts');
if ($method->isModelRelation()) {
    // Este método es una relación
}
```

<Info>
  Como Surveyor intenta conectarse a la base de datos al analizar modelos Eloquent, no es un análisis puramente estático. Además, el rendimiento y el uso de memoria están actualmente en proceso de mejora, y se agradecen las contribuciones.
</Info>

***

## laravel/ranger — Introspección de alto nivel

[laravel/ranger](https://github.com/laravel/ranger) es una biblioteca de alto nivel que envuelve surveyor y recorre toda la aplicación Laravel para recopilar información sobre rutas, modelos, Enums, eventos de broadcast, variables de entorno, componentes Inertia y más.

### Instalación

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

### Uso básico

En formato de callback, describes el procesamiento cuando se descubre cada componente.

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

$ranger = app(Ranger::class);

// Se invoca cada vez que se descubre una ruta
$ranger->onRoute(function (Components\Route $route) {
    echo $route->uri();
});

// Se invoca cada vez que se descubre un modelo
$ranger->onModel(function (Components\Model $model) {
    foreach ($model->getAttributes() as $name => $type) {
        // Procesamiento del nombre y tipo del atributo
    }
});

// Se invoca cada vez que se descubre un Enum
$ranger->onEnum(function (Components\Enum $enum) {
    //
});

// Se invoca cada vez que se descubre un evento de broadcast
$ranger->onBroadcastEvent(function (Components\BroadcastEvent $event) {
    //
});

// Se invoca una sola vez después de recolectar todas las rutas
$ranger->onRoutes(function (Collection $routes) {
    //
});

// Se invoca una sola vez después de recolectar todos los modelos
$ranger->onModels(function (Collection $models) {
    //
});

// Recorre toda la aplicación y dispara los callbacks
$ranger->walk();
```

### Componentes que recoge Ranger

| Colector                 | Descripción                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Routes**               | Todas las rutas registradas (URI, parámetros, métodos HTTP, controlador, reglas de validación, respuesta) |
| **Models**               | Modelos Eloquent y sus atributos, tipos y relaciones                                                      |
| **Enums**                | Backed Enums de PHP (Enums con entero o cadena) y sus cases y valores                                     |
| **BroadcastEvents**      | Eventos que implementan `ShouldBroadcast` y su payload                                                    |
| **BroadcastChannels**    | Canales de broadcast registrados                                                                          |
| **EnvironmentVariables** | Variables de entorno definidas en el archivo `.env`                                                       |
| **Inertia Shared Data**  | Props globalmente compartidas de Inertia.js                                                               |
| **Inertia Components**   | Componentes de página de Inertia.js y las props esperadas                                                 |

***

## laravel/roster — Herramienta de detección de paquetes

[laravel/roster](https://github.com/laravel/roster) es una herramienta que detecta qué paquetes del ecosistema Laravel están instalados en un proyecto. Los desarrolladores de paquetes y autores de herramientas pueden obtener fácilmente información como "¿este proyecto usa Inertia?" o "¿qué versión de Livewire?".

### Instalación

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

### Uso básico

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

// Escanear un directorio y obtener Roster
$roster = Roster::scan($directory);

// Listado de paquetes instalados
$roster->packages();

// Solo paquetes de producción
$roster->packages()->production();

// Solo paquetes exclusivos de desarrollo
$roster->packages()->dev();

// Comprobar la presencia de un paquete concreto
$roster->uses(Packages::INERTIA);        // bool
$roster->uses(Packages::LIVEWIRE);       // bool

// Comprobar especificando condición de versión
$roster->usesVersion(Packages::INERTIA, '2.0.0', '>=');   // ¿Inertia 2.0.0 o superior?
$roster->usesVersion(Packages::LIVEWIRE, '3.0.0', '>=');  // ¿Livewire 3.0.0 o superior?

// Detección del gestor de paquetes JavaScript
$packageManager = $roster->nodePackageManager(); // 'npm', 'yarn', 'bun', etc.
```

***

## Casos de uso reales

### Herramienta de generación de directrices para IA (Boost)

[Laravel Boost](https://github.com/laravel/boost) usa roster para entender la configuración de paquetes instalados y ajustar automáticamente la generación de directrices y skills para agentes de IA (GitHub Copilot, Claude, etc.). Basándose en información como "¿este proyecto usa Inertia?" o "¿está instalado Livewire?", selecciona los archivos de directrices adecuados y los proporciona al agente de IA.

```mermaid theme={null}
sequenceDiagram
    participant Boost as Laravel Boost
    participant Roster as laravel/roster
    participant AI as Agente de IA
    Boost->>Roster: Roster::scan(base_path())
    Roster->>Boost: packages() [Inertia, Livewire, Pint...]
    Boost->>Boost: Selecciona directrices por paquete
    Boost->>AI: Directrices de Inertia, directrices de Livewire...
```

### Crear un verificador de compatibilidad de paquetes

Cuando desarrollas un paquete que cambia su comportamiento según los paquetes instalados en el proyecto del usuario, roster resulta muy útil.

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

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

if ($roster->uses(Packages::INERTIA)) {
    // Procesamiento para Inertia
    if ($roster->usesVersion(Packages::INERTIA, '2.0.0', '>=')) {
        // Procesamiento para Inertia v2 o superior
    }
}

if ($roster->uses(Packages::LIVEWIRE)) {
    // Procesamiento para Livewire
}

// Cambiar el comando de instalación según el gestor de paquetes JavaScript
$pm = $roster->nodePackageManager();
echo "Run: {$pm} install your-package";
```

### Generación automática de documentación de la aplicación

Con ranger puedes construir una herramienta que recolecta automáticamente las rutas, modelos y Enums de una app Laravel y genera documentación.

```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(),
        // También se pueden obtener reglas de validación, tipos de respuesta, etc.
    ];
});

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

$ranger->walk();

// En $docs se recoge la información estructural de toda la app
```

***

## Conclusión

surveyor, ranger y roster proporcionan una nueva base para el **análisis de código programático** en el ecosistema Laravel.

```mermaid theme={null}
graph LR
    A["surveyor<br>Parsea archivos PHP<br>Extrae clases, métodos y tipos"] --> B["ranger<br>Recorre toda la app Laravel<br>Recoge rutas, modelos y Enums"]
    B --> C["roster<br>Detecta paquetes instalados<br>Comprueba versiones y tipos"]
```

Estos paquetes están dirigidos principalmente a desarrolladores de paquetes y autores de herramientas, no son algo que use directamente el usuario final. Sin embargo, se aprovechan activamente en el interior de herramientas oficiales de Laravel como Laravel Boost, y se espera que su uso siga ampliándose en el ecosistema.

<Columns cols={3}>
  <Card title="laravel/surveyor" icon="github" href="https://github.com/laravel/surveyor">
    Motor de análisis estático de código PHP
  </Card>

  <Card title="laravel/ranger" icon="github" href="https://github.com/laravel/ranger">
    Biblioteca de introspección de alto nivel
  </Card>

  <Card title="laravel/roster" icon="github" href="https://github.com/laravel/roster">
    Herramienta de detección de paquetes
  </Card>
</Columns>


## Related topics

- [laravel/agent-skills — Colección oficial de skills para agentes de IA de Laravel](/es/blog/agent-skills-introduction.md)
- [Laravel Sentinel — Investigación del middleware de protección de rutas](/es/blog/sentinel-introduction.md)
- [Laravel Agent Detector — Paquete de detección de agentes de IA](/es/blog/agent-detector-introduction.md)
- [Laravel Chisel — Biblioteca de scripts de post-instalación para starter kits](/es/blog/chisel-introduction.md)
- [Laravel Maestro — Orquestador de desarrollo de starter kits](/es/blog/maestro-introduction.md)