Il nuovo ecosistema di analisi del codice Laravel — surveyor / ranger / roster

Presentiamo i tre pacchetti (surveyor, ranger, roster) che compongono l’ecosistema di analisi statica pubblicato da Laravel. Dal parsing del codice PHP al rilevamento dei pacchetti, spieghiamo il nuovo insieme di strumenti che sviluppatori di pacchetti e autori di tool dovrebbero conoscere.

Questo articolo si basa sui README e sul codice sorgente dei repository GitHub. I tre pacchetti sono tutti in versione Beta prima del rilascio stabile (dato di aprile 2026).

surveyor, ranger e roster sono tutti in rilascio Beta. L’API potrebbe cambiare prima del rilascio di v1.0.0. Valuta con attenzione l’uso in produzione.

​

Ultime release (aprile 2026)

Pacchetto	Ultima release	Nota
laravel/roster	v0.5.1	Nel composer.json di laravel/boost è richiesto ^0.5.0 e in BoostServiceProvider viene eseguito Roster::scan(base_path())
laravel/ranger	v0.1.12	Nel composer.json dipende da laravel/surveyor:^0.1.0
laravel/surveyor	v0.1.9	Layer basso usato come base di analisi da ranger

​

Panoramica

All’inizio del 2026 Laravel ha pubblicato tre pacchetti relativi all’analisi del codice. Ciascuno può essere usato da solo, ma insieme formano un ecosistema di analisi del codice integrato.

Pacchetto	Ruolo	Installazione
laravel/surveyor	Motore di analisi statica del codice PHP	composer require laravel/surveyor
laravel/ranger	Introspezione dell’intera app Laravel	composer require laravel/ranger
laravel/roster	Rilevamento dei pacchetti dell’ecosistema	composer require laravel/roster --dev

Vediamo nel dettaglio ogni pacchetto in ordine.

---

​

laravel/surveyor — motore di analisi statica

laravel/surveyor è uno strumento di analisi statica che effettua il parsing di file PHP e fornisce meta-informazioni dettagliate su classi, metodi, proprietà, tipi di ritorno, ecc., in formato strutturato. È specializzato nell’estrarre informazioni in un formato utilizzabile da altri tool e pacchetti.

​

Installazione

composer require laravel/surveyor

​

Uso di base

​

Analizzare un file

use Laravel\Surveyor\Analyzer\Analyzer;

$analyzer = app(Analyzer::class);

// Analizza tramite path del file
$result = $analyzer->analyze('/path/to/your/File.php');

// Accedi allo scope analizzato
$scope = $result->analyzed();

// Accedi al risultato della classe
$classResult = $result->result();

​

Analizzare direttamente una classe

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

​

Informazioni ottenibili con ClassResult

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

// Informazioni sulla classe
$name = $classResult->name();            // 'App\Models\User'
$namespace = $classResult->namespace();  // 'App\Models'
$filePath = $classResult->filePath();

// Ereditarietà
$extends = $classResult->extends();
$implements = $classResult->implements();

// Informazioni sui metodi
$method = $classResult->getMethod('store');
$returnType = $method->returnType();
$parameters = $method->parameters();
$rules = $method->validationRules(); // Sono ottenibili anche le regole di validazione

// Informazioni sulle proprietà
$property = $classResult->getProperty('email');
$type = $property->type;
$visibility = $property->visibility; // 'public', 'protected', 'private'

// Elenco di metodi e proprietà pubblici
$publicMethods = $classResult->publicMethods();
$publicProperties = $classResult->publicProperties();

​

Sistema di tipi

Surveyor ha un sistema di tipi ricco che permette di trattare i tipi PHP in modo strutturato.

use Laravel\Surveyor\Types\Type;

// Creazione dei vari tipi
$stringType = Type::string();
$intType = Type::int();
$boolType = Type::bool();
$nullType = Type::null();

// Tipo unione (string|null, ecc.)
$unionType = Type::union(Type::string(), Type::null());

// Verifica del tipo
use Laravel\Surveyor\Types\StringType;

if (Type::is($returnType, StringType::class)) {
    // Elaborazione per tipo stringa
}

​

Configurazione della cache

Puoi memorizzare in cache i risultati di analisi per migliorare le prestazioni delle esecuzioni ripetute.

use Laravel\Surveyor\Analyzer\AnalyzedCache;

// Abilita la cache su disco
AnalyzedCache::enableDiskCache(storage_path('surveyor-cache'));

// Cancella la cache
AnalyzedCache::clear();

Puoi configurarla anche tramite variabili d’ambiente.

SURVEYOR_CACHE_ENABLED=true
SURVEYOR_CACHE_DIR=/path/to/cache

​

Analisi dei modelli Eloquent

Surveyor prova a connettersi al database e analizza in modo speciale i modelli Eloquent. Rileva anche relazioni, attributi, accessor e cast del modello.

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

// Gli attributi del database vengono rilevati automaticamente
$emailProperty = $result->getProperty('email');

// Determinare se un metodo è una relazione
$method = $result->getMethod('posts');
if ($method->isModelRelation()) {
    // Questo metodo è una relazione
}

Poiché Surveyor tenta di connettersi al database durante l’analisi dei modelli Eloquent, non è un’analisi completamente statica. Inoltre, prestazioni e uso di memoria sono in fase di miglioramento e i contributi sono benvenuti.

---

​

laravel/ranger — introspezione ad alto livello

laravel/ranger è una libreria ad alto livello che avvolge surveyor e attraversa l’intera applicazione Laravel per raccogliere informazioni su rotte, modelli, Enum, eventi broadcast, variabili d’ambiente e componenti Inertia.

​

Installazione

composer require laravel/ranger

​

Uso di base

In stile callback, descrivi come processare ciascun componente quando viene scoperto.

use Laravel\Ranger\Ranger;
use Laravel\Ranger\Components;
use Illuminate\Support\Collection;

$ranger = app(Ranger::class);

// Chiamata a ogni rotta scoperta
$ranger->onRoute(function (Components\Route $route) {
    echo $route->uri();
});

// Chiamata a ogni modello scoperto
$ranger->onModel(function (Components\Model $model) {
    foreach ($model->getAttributes() as $name => $type) {
        // Elaborazione di nome e tipo dell'attributo
    }
});

// Chiamata a ogni Enum scoperto
$ranger->onEnum(function (Components\Enum $enum) {
    //
});

// Chiamata a ogni evento broadcast scoperto
$ranger->onBroadcastEvent(function (Components\BroadcastEvent $event) {
    //
});

// Chiamata una sola volta dopo la raccolta di tutte le rotte
$ranger->onRoutes(function (Collection $routes) {
    //
});

// Chiamata una sola volta dopo la raccolta di tutti i modelli
$ranger->onModels(function (Collection $models) {
    //
});

// Attraversa l'intera applicazione e attiva le callback
$ranger->walk();

​

Componenti raccolti da Ranger

Collector	Descrizione
Routes	Tutte le rotte registrate (URI, parametri, metodo HTTP, controller, regole di validazione, risposta)
Models	Modelli Eloquent con attributi, tipi e relazioni
Enums	Backed Enum di PHP (Enum con intero o stringa) con case e valori
BroadcastEvents	Eventi che implementano ShouldBroadcast e i loro payload
BroadcastChannels	Canali broadcast registrati
EnvironmentVariables	Variabili d’ambiente definite in .env
Inertia Shared Data	Prop di Inertia.js condivise globalmente
Inertia Components	Componenti pagina di Inertia.js e prop attese

---

​

laravel/roster — strumento di rilevamento pacchetti

laravel/roster è uno strumento che rileva quali pacchetti dell’ecosistema Laravel sono installati in un progetto. Sviluppatori di pacchetti e autori di tool possono facilmente ottenere informazioni come “questo progetto usa Inertia?” o “quale versione di Livewire?”.

​

Installazione

composer require laravel/roster --dev

​

Uso di base

use Laravel\Roster\Roster;
use Laravel\Roster\Packages;

// Scansiona una directory per ottenere Roster
$roster = Roster::scan($directory);

// Elenco dei pacchetti installati
$roster->packages();

// Solo pacchetti di produzione
$roster->packages()->production();

// Solo pacchetti di sviluppo
$roster->packages()->dev();

// Verifica la presenza di un pacchetto specifico
$roster->uses(Packages::INERTIA);        // bool
$roster->uses(Packages::LIVEWIRE);       // bool

// Verifica con condizione di versione
$roster->usesVersion(Packages::INERTIA, '2.0.0', '>=');   // Inertia 2.0.0 o superiore?
$roster->usesVersion(Packages::LIVEWIRE, '3.0.0', '>=');  // Livewire 3.0.0 o superiore?

// Rilevamento del package manager JavaScript
$packageManager = $roster->nodePackageManager(); // 'npm', 'yarn', 'bun', ecc.

---

​

Casi d’uso reali

​

Strumento di generazione di linee guida AI (Boost)

Laravel Boost usa roster per conoscere la composizione dei pacchetti installati e regolare automaticamente la generazione di linee guida e skill per agenti AI (come GitHub Copilot o Claude). Basandosi su informazioni come “questo progetto usa Inertia?” o “è installato Livewire?”, seleziona i file di linee guida appropriati e li fornisce all’agente AI.

​

Creare un checker di compatibilità tra pacchetti

Se sviluppi un pacchetto il cui comportamento cambia in base ai pacchetti installati nel progetto dell’utente, roster è molto utile.

use Laravel\Roster\Roster;
use Laravel\Roster\Packages;

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

if ($roster->uses(Packages::INERTIA)) {
    // Elaborazione per Inertia
    if ($roster->usesVersion(Packages::INERTIA, '2.0.0', '>=')) {
        // Elaborazione per Inertia v2 o superiore
    }
}

if ($roster->uses(Packages::LIVEWIRE)) {
    // Elaborazione per Livewire
}

// Cambia il comando di installazione in base al package manager JavaScript
$pm = $roster->nodePackageManager();
echo "Run: {$pm} install your-package";

​

Generazione automatica di documentazione dell’applicazione

Usando ranger puoi costruire uno strumento che raccoglie automaticamente rotte, modelli ed Enum di un’app Laravel e genera documentazione.

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(),
        // Puoi ottenere anche regole di validazione e tipi di risposta della rotta
    ];
});

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

$ranger->walk();

// In $docs vengono raccolte le informazioni strutturali dell'intera app

---

​

Conclusioni

surveyor, ranger e roster forniscono una nuova base per l’analisi programmatica del codice nell’ecosistema Laravel.

Questi pacchetti sono pensati principalmente per sviluppatori di pacchetti e autori di tool, non per l’utente finale. Tuttavia sono già utilizzati attivamente all’interno degli strumenti ufficiali di Laravel come Laravel Boost e ci si aspetta un’ulteriore espansione dell’ecosistema.

laravel/surveyor

Motore di analisi statica del codice PHP

laravel/ranger

Libreria di introspezione ad alto livello

laravel/roster

Strumento di rilevamento pacchetti