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.

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

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.

​

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

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

composer require laravel/surveyor

​

Utilisation de base

​

Analyser un fichier

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

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

​

Informations disponibles via ClassResult

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

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.

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.

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.

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

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.

---

​

laravel/ranger — introspection de haut niveau

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

composer require laravel/ranger

​

Utilisation de base

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

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

composer require laravel/roster --dev

​

Utilisation de base

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

​

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.

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.

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.

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.

laravel/surveyor

Moteur d’analyse statique de code PHP

laravel/ranger

Bibliothèque d’introspection de haut niveau

laravel/roster

Outil de détection de packages