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

# Le nouvel écosystème d'analyse de code Laravel — surveyor / ranger / roster

> Présentation des trois packages composant l'écosystème d'analyse statique publié par Laravel (surveyor, ranger, roster). De l'analyse de code PHP à la détection de packages, un tour d'horizon des nouveaux outils que doivent connaître les développeurs de packages et d'outils.

<Info>
  Cet article s'appuie sur les README des dépôts GitHub et le code source. Les trois packages sont encore en version Beta (à la date d'avril 2026).
</Info>

<Warning>
  surveyor, ranger et roster sont tous en **release Beta**. L'API peut changer avant la sortie v1.0.0. Évaluez avec prudence toute utilisation en production.
</Warning>

## État des dernières releases (avril 2026)

| Package            | Dernière release | Notes                                                                                                                            |
| ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `laravel/roster`   | `v0.5.1`         | Exigé en `^0.5.0` dans le `composer.json` de `laravel/boost`, `Roster::scan(base_path())` est appelé dans `BoostServiceProvider` |
| `laravel/ranger`   | `v0.1.12`        | Dépend de `laravel/surveyor:^0.1.0` dans son `composer.json`                                                                     |
| `laravel/surveyor` | `v0.1.9`         | Couche basse utilisée comme moteur d'analyse par `ranger`                                                                        |

## Vue d'ensemble

Depuis le début 2026, Laravel a publié trois packages liés à l'analyse de code. Ils sont utilisables individuellement, mais forment un **écosystème d'analyse de code** interconnecté.

```mermaid theme={null}
graph TD
    A["laravel/roster<br>Détection de packages"] --> B["laravel/ranger<br>Introspection de haut niveau"]
    B --> C["laravel/surveyor<br>Moteur d'analyse statique bas niveau"]
    D["Boost<br>Outil d'assistance IA"] --> A
    E["Développeurs d'outils et de packages"] --> A
    E --> B
    E --> C
```

| Package            | Rôle                                             | Installation                            |
| ------------------ | ------------------------------------------------ | --------------------------------------- |
| `laravel/surveyor` | Moteur d'analyse statique de code PHP            | `composer require laravel/surveyor`     |
| `laravel/ranger`   | Introspection d'une application Laravel complète | `composer require laravel/ranger`       |
| `laravel/roster`   | Détection des packages de l'écosystème           | `composer require laravel/roster --dev` |

Détaillons chaque package.

***

## laravel/surveyor — moteur d'analyse statique

[laravel/surveyor](https://github.com/laravel/surveyor) est un outil d'analyse statique qui parse des fichiers PHP et fournit sous forme structurée des métadonnées détaillées sur les classes, méthodes, propriétés, types de retour, etc. Il est spécialisé dans l'extraction d'informations exploitables par d'autres outils ou packages.

### Installation

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

### Utilisation de base

#### Analyser un fichier

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

$analyzer = app(Analyzer::class);

// Analyser par chemin de fichier
$result = $analyzer->analyze('/path/to/your/File.php');

// Accéder au scope analysé
$scope = $result->analyzed();

// Accéder au résultat de la classe
$classResult = $result->result();
```

#### Analyser une classe directement

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

### Informations disponibles via ClassResult

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

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

// Héritage
$extends = $classResult->extends();
$implements = $classResult->implements();

// Infos de méthode
$method = $classResult->getMethod('store');
$returnType = $method->returnType();
$parameters = $method->parameters();
$rules = $method->validationRules(); // Les règles de validation sont aussi accessibles

// Infos de propriété
$property = $classResult->getProperty('email');
$type = $property->type;
$visibility = $property->visibility; // 'public', 'protected', 'private'

// Listes des méthodes et propriétés publiques
$publicMethods = $classResult->publicMethods();
$publicProperties = $classResult->publicProperties();
```

### Système de types

Surveyor dispose d'un système de types riche qui permet de manipuler les types PHP de manière structurée.

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

// Création de types divers
$stringType = Type::string();
$intType = Type::int();
$boolType = Type::bool();
$nullType = Type::null();

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

// Vérification de type
use Laravel\Surveyor\Types\StringType;

if (Type::is($returnType, StringType::class)) {
    // Traitement pour un type chaîne
}
```

### Configuration du cache

Vous pouvez mettre en cache les résultats d'analyse pour améliorer les performances lors d'exécutions répétées.

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

// Activer le cache sur disque
AnalyzedCache::enableDiskCache(storage_path('surveyor-cache'));

// Vider le cache
AnalyzedCache::clear();
```

Configurable également via des variables d'environnement.

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

### Analyse des modèles Eloquent

Surveyor traite spécialement les modèles Eloquent en tentant de se connecter à la base de données. Les relations, attributs, accesseurs et casts du modèle sont détectés.

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

// Les attributs de base sont détectés automatiquement
$emailProperty = $result->getProperty('email');

// Détecter une méthode de relation
$method = $result->getMethod('posts');
if ($method->isModelRelation()) {
    // Cette méthode est une relation
}
```

<Info>
  Surveyor tente de se connecter à la base de données lors de l'analyse d'un modèle Eloquent : ce n'est donc pas une analyse purement statique. Les performances et la consommation mémoire sont en cours d'amélioration ; les contributions sont bienvenues.
</Info>

***

## laravel/ranger — introspection de haut niveau

[laravel/ranger](https://github.com/laravel/ranger) est une bibliothèque de haut niveau qui enveloppe surveyor et parcourt l'application Laravel complète pour collecter : routes, modèles, Enum, événements de broadcast, variables d'environnement, composants Inertia, etc.

### Installation

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

### Utilisation de base

Vous écrivez des callbacks qui sont exécutés lorsqu'un composant est découvert.

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

$ranger = app(Ranger::class);

// Appelé à chaque route découverte
$ranger->onRoute(function (Components\Route $route) {
    echo $route->uri();
});

// Appelé à chaque modèle découvert
$ranger->onModel(function (Components\Model $model) {
    foreach ($model->getAttributes() as $name => $type) {
        // Traitement du nom d'attribut et du type
    }
});

// Appelé à chaque Enum découvert
$ranger->onEnum(function (Components\Enum $enum) {
    //
});

// Appelé à chaque événement de broadcast découvert
$ranger->onBroadcastEvent(function (Components\BroadcastEvent $event) {
    //
});

// Appelé une seule fois après collecte de toutes les routes
$ranger->onRoutes(function (Collection $routes) {
    //
});

// Appelé une seule fois après collecte de tous les modèles
$ranger->onModels(function (Collection $models) {
    //
});

// Parcourir toute l'application et déclencher les callbacks
$ranger->walk();
```

### Composants collectés par Ranger

| Collecteur               | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Routes**               | Toutes les routes enregistrées (URI, paramètres, méthode HTTP, contrôleur, règles de validation, réponse) |
| **Models**               | Modèles Eloquent et leurs attributs, types, relations                                                     |
| **Enums**                | Backed Enums PHP (à valeur entière ou chaîne), cas et valeurs                                             |
| **BroadcastEvents**      | Événements implémentant `ShouldBroadcast` et leurs payloads                                               |
| **BroadcastChannels**    | Canaux de broadcast enregistrés                                                                           |
| **EnvironmentVariables** | Variables d'environnement définies dans le fichier `.env`                                                 |
| **Inertia Shared Data**  | Props Inertia.js partagés globalement                                                                     |
| **Inertia Components**   | Composants de page Inertia.js et props attendues                                                          |

***

## laravel/roster — outil de détection de packages

[laravel/roster](https://github.com/laravel/roster) détecte quels packages de l'écosystème Laravel sont installés dans le projet. Les développeurs de packages et d'outils peuvent facilement savoir « ce projet utilise-t-il Inertia ? », « quelle est la version de Livewire ? », etc.

### Installation

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

### Utilisation de base

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

// Scanner un répertoire et obtenir le Roster
$roster = Roster::scan($directory);

// Liste des packages installés
$roster->packages();

// Uniquement les packages de production
$roster->packages()->production();

// Uniquement les packages de développement
$roster->packages()->dev();

// Vérifier la présence d'un package
$roster->uses(Packages::INERTIA);        // bool
$roster->uses(Packages::LIVEWIRE);       // bool

// Vérifier avec une contrainte de version
$roster->usesVersion(Packages::INERTIA, '2.0.0', '>=');   // Inertia >= 2.0.0 ?
$roster->usesVersion(Packages::LIVEWIRE, '3.0.0', '>=');  // Livewire >= 3.0.0 ?

// Détection du package manager JavaScript
$packageManager = $roster->nodePackageManager(); // 'npm', 'yarn', 'bun', etc.
```

***

## Cas d'usage concrets

### Outil de génération de guidelines IA (Boost)

[Laravel Boost](https://github.com/laravel/boost) s'appuie sur roster pour connaître les packages installés et adapte automatiquement la génération de guidelines et de skills destinés aux agents IA (GitHub Copilot, Claude, etc.). Selon que « le projet utilise Inertia ou non » ou « Livewire est présent ou non », il sélectionne les fichiers de guidelines adéquats à fournir à l'agent IA.

```mermaid theme={null}
sequenceDiagram
    participant Boost as Laravel Boost
    participant Roster as laravel/roster
    participant AI as Agent IA
    Boost->>Roster: Roster::scan(base_path())
    Roster->>Boost: packages() [Inertia, Livewire, Pint...]
    Boost->>Boost: Sélectionne les guidelines par package
    Boost->>AI: Guidelines Inertia, guidelines Livewire...
```

### Créer un checker de compatibilité de packages

Si vous développez un package dont le comportement varie en fonction des packages installés dans le projet utilisateur, roster est très pratique.

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

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

if ($roster->uses(Packages::INERTIA)) {
    // Traitement pour Inertia
    if ($roster->usesVersion(Packages::INERTIA, '2.0.0', '>=')) {
        // Traitement pour Inertia v2 ou supérieur
    }
}

if ($roster->uses(Packages::LIVEWIRE)) {
    // Traitement pour Livewire
}

// Adapter la commande d'installation selon le package manager JavaScript
$pm = $roster->nodePackageManager();
echo "Run: {$pm} install your-package";
```

### Génération automatique de documentation d'application

Avec ranger, vous pouvez construire un outil qui collecte automatiquement routes, modèles et Enums pour générer de la 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(),
        // Vous pouvez aussi récupérer les règles de validation et le type de réponse
    ];
});

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

$ranger->walk();

// $docs contient les informations structurelles de toute l'application
```

***

## Conclusion

surveyor, ranger et roster fournissent une nouvelle fondation pour **l'analyse programmatique de code** dans l'écosystème Laravel.

```mermaid theme={null}
graph LR
    A["surveyor<br>Parse les fichiers PHP<br>Extrait classes, méthodes, types"] --> B["ranger<br>Parcourt toute l'application Laravel<br>Collecte routes, modèles, Enums"]
    B --> C["roster<br>Détecte les packages installés<br>Vérifie versions et types"]
```

Ces packages ciblent principalement les développeurs de packages et d'outils, et ne sont pas destinés aux utilisateurs finaux. Ils sont néanmoins déjà utilisés en interne par des outils officiels Laravel comme Laravel Boost, et devraient continuer à étendre l'écosystème.

<Columns cols={3}>
  <Card title="laravel/surveyor" icon="github" href="https://github.com/laravel/surveyor">
    Moteur d'analyse statique de code PHP
  </Card>

  <Card title="laravel/ranger" icon="github" href="https://github.com/laravel/ranger">
    Bibliothèque d'introspection de haut niveau
  </Card>

  <Card title="laravel/roster" icon="github" href="https://github.com/laravel/roster">
    Outil de détection de packages
  </Card>
</Columns>


## Related topics

- [Laravel et le développement IA](/fr/ai.md)
- [Première analyse de Laravel Passkeys (passkeys-server + @laravel/passkeys)](/fr/blog/passkeys-introduction.md)
- [Laravel Sentinel — analyse du middleware de protection des routes](/fr/blog/sentinel-introduction.md)
- [Analyse statique de packages (PHPStan / Larastan)](/fr/advanced/package-static-analysis.md)
- [laravel/agent-skills — la collection officielle de skills d'agents IA Laravel](/fr/blog/agent-skills-introduction.md)