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

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

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

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

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

```mermaid theme={null}
graph TD
    A["laravel/roster<br>Rilevamento pacchetti"] --> B["laravel/ranger<br>Introspezione ad alto livello"]
    B --> C["laravel/surveyor<br>Motore di analisi statica a basso livello"]
    D["Boost<br>Tool di supporto allo sviluppo AI"] --> A
    E["Sviluppatori di tool e pacchetti"] --> A
    E --> B
    E --> C
```

| 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](https://github.com/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

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

### Uso di base

#### Analizzare un file

```php theme={null}
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

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

### Informazioni ottenibili con ClassResult

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
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.

```env theme={null}
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.

```php theme={null}
$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
}
```

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

***

## laravel/ranger — introspezione ad alto livello

[laravel/ranger](https://github.com/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

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

### Uso di base

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

```php theme={null}
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](https://github.com/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

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

### Uso di base

```php theme={null}
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](https://github.com/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.

```mermaid theme={null}
sequenceDiagram
    participant Boost as Laravel Boost
    participant Roster as laravel/roster
    participant AI as Agente AI
    Boost->>Roster: Roster::scan(base_path())
    Roster->>Boost: packages() [Inertia, Livewire, Pint...]
    Boost->>Boost: Selezione delle linee guida per pacchetto
    Boost->>AI: Linee guida Inertia, linee guida Livewire...
```

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

```php theme={null}
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.

```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(),
        // 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.

```mermaid theme={null}
graph LR
    A["surveyor<br>Fa il parsing di file PHP<br>Estrae classi, metodi, tipi"] --> B["ranger<br>Percorre l'intera app Laravel<br>Raccoglie rotte, modelli, Enum"]
    B --> C["roster<br>Rileva i pacchetti installati<br>Verifica versione e tipo"]
```

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.

<Columns cols={3}>
  <Card title="laravel/surveyor" icon="github" href="https://github.com/laravel/surveyor">
    Motore di analisi statica del codice PHP
  </Card>

  <Card title="laravel/ranger" icon="github" href="https://github.com/laravel/ranger">
    Libreria di introspezione ad alto livello
  </Card>

  <Card title="laravel/roster" icon="github" href="https://github.com/laravel/roster">
    Strumento di rilevamento pacchetti
  </Card>
</Columns>


## Related topics

- [Migration del database](/it/migrations.md)
- [laravel/agent-skills — la raccolta ufficiale di skill per agenti AI di Laravel](/it/blog/agent-skills-introduction.md)
- [Laravel e lo sviluppo con AI](/it/ai.md)
- [Laravel Chisel — libreria di script post-installazione per starter kit](/it/blog/chisel-introduction.md)
- [Laravel Sentinel — indagine sul middleware di protezione delle rotte](/it/blog/sentinel-introduction.md)