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.

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).

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.

​

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í.

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 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

composer require laravel/surveyor

​

Uso básico

​

Analizar un archivo

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

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

​

Información obtenible con ClassResult

$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.

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.

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.

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.

$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
}

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.

---

​

laravel/ranger — Introspección de alto nivel

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

composer require laravel/ranger

​

Uso básico

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

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 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

composer require laravel/roster --dev

​

Uso básico

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 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.

​

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.

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.

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.

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.

laravel/surveyor

Motor de análisis estático de código PHP

laravel/ranger

Biblioteca de introspección de alto nivel

laravel/roster

Herramienta de detección de paquetes