Laravel PAO : une sortie propre pour les agents IA

Les développeurs PHP et Laravel tournent en boucle toute la journée : tester, corriger, analyser, refactoriser, tester encore. Les outils de ce quotidien produisent une sortie taillée pour les terminaux humains, avec des couleurs ANSI, des points de tabulation et des tableaux décorés. C'est parfait quand vous lisez la sortie vous-même. Mais c'est du bruit quand c'est un agent qui le fait.

Pour un agent, ce même affichage peut masquer l'essentiel : l'assertion qui échoue, le chemin de fichier, le numéro de ligne, l'identifiant PHPStan, le diff Rector.

Laravel PAO (PHP agent-optimized output) règle ce problème. Il détecte quand les outils PHP supportés sont exécutés par un agent IA, comme Claude Code, Cursor, Devin ou Gemini CLI. Pour les outils de test et d'analyse, PAO retourne du JSON compact et structuré. Pour les commandes Artisan, il nettoie la sortie console décorée pour que les agents reçoivent la même information avec moins de bruit.

À partir d'aujourd'hui, les nouvelles applications Laravel incluent PAO comme dépendance de développement par défaut.

Ce qui change concrètement

Prenez une large suite PHPUnit. Sans Laravel PAO, un agent reçoit des centaines de caractères de progression avant de savoir si la suite est passée ou non :

1PHPUnit 12.5.14 by Sebastian Bergmann and contributors.........
2...............................................................
31002 / 1002 (100%)
4
5Time: 00:00.321, Memory: 46.50 MB
6OK (1002 tests, 1002 assertions)

Avec Laravel PAO, l'agent reçoit ceci à la place :

1{"tool":"phpunit","result":"passed","tests":1002,"passed":1002,"duration_ms":321}

La différence semble anodine dans un article, mais elle compte énormément dans une session agent. La sortie reste compacte quel que soit le nombre de tests qui passent.

Les échecs deviennent aussi bien plus exploitables. Au lieu de demander à l'agent de fouiller une sortie de terminal formatée, PAO lui fournit directement les détails dont il a besoin pour continuer à travailler :

 1{
 2  "tool": "phpunit",
 3  "result": "failed",
 4  "tests": 2,
 5  "passed": 1,
 6  "failed": 1,
 7  "failures": [
 8    {
 9      "test": "Tests\\Feature\\ExampleTest::it_returns_a_successful_response",
10      "file": "tests/Feature/ExampleTest.php",
11      "line": 17,
12      "message": "Failed asserting that 500 is identical to 200."
13    }
14  ]
15}

L'agent sait ce qui a échoué, où c'est arrivé, et quel message il doit traiter pour continuer.

Les outils que vous utilisez déjà, sans rien changer

Laravel PAO supporte actuellement PHPUnit, Pest, Paratest, PHPStan, Rector et la sortie Laravel Artisan.

Pour PHPUnit, Pest et Paratest, PAO rapporte des résultats compacts : comptages, durées, échecs, erreurs, tests ignorés, avertissements, notices et dépréciations. Les sorties supplémentaires utiles comme la couverture de code ou les résumés de profiling sont nettoyées et incluses sans la décoration de terminal qui les entoure.

La sortie PHPStan est normalisée en JSON centré sur le nombre total d'erreurs et les détails par fichier dont les agents ont besoin pour les corriger :

 1{
 2  "tool": "phpstan",
 3  "result": "failed",
 4  "errors": 2,
 5  "error_details": {
 6    "app/Http/Controllers/Controller.php": [
 7      {
 8        "line": 9,
 9        "message": "Method Controller::index() should return int but returns string.",
10        "identifier": "return.type"
11      }
12    ]
13  }
14}

La sortie Rector est elle aussi rendue plus exploitable pour les agents, en préservant les fichiers modifiés, les diffs et les rectors appliqués dans un format structuré.

L'objectif n'est pas d'inventer un nouveau workflow. C'est de rendre le workflow que les développeurs Laravel utilisent déjà plus facile à suivre pour les agents.

Artisan : même information, moins de tokens

Pour les commandes Artisan, le résultat n'est pas du JSON. C'est la même sortie de commande avec la décoration retirée.

Des commandes comme about, db:show ou migrate:status produisent souvent des tableaux décorés, des points de tabulation, des couleurs et de l'espacement. Ces détails rendent la sortie agréable pour les humains, mais les agents n'en ont pas besoin.

Par exemple, une sortie comme celle-ci :

1Environment ................................................................
2Application Name ................................................... Laravel
3Laravel Version ..................................................... 13.3.0
4PHP Version .......................................................... 8.5.4
5Debug Mode ......................................................... ENABLED

Devient :

1Environment ..
2Application Name .. Laravel
3Laravel Version .. 13.3.0
4PHP Version .. 8.5.4
5Debug Mode .. ENABLED

Même information, moins de tokens à traiter pour l'agent.

Votre terminal reste identique

C'est le point important : Laravel PAO ne change pas l'expérience terminal pour vous ou votre équipe.

Quand vous lancez phpunit, pest, phpstan, rector ou artisan directement dans votre terminal, la sortie reste identique. PAO ne s'active que quand un agent est détecté. Laravel obtient ainsi de meilleures valeurs par défaut pour le développement assisté par IA, sans dégrader l'expérience humaine.

Comment PAO fonctionne sous le capot

Laravel PAO n'introduit pas de nouveau binaire et ne vous demande pas de lancer une commande différente. Il démarre via l'autoload de fichiers de Composer, ce qui lui permet de s'exécuter tôt dans le processus PHP :

1{
2  "autoload": {
3    "files": [
4      "src/Autoload.php"
5    ]
6  }
7}

Ce fichier d'autoload quitte immédiatement s'il ne détecte pas un environnement agent :

1$agent = AgentDetector::detect();
2 
3if (! $agent->isAgent) {
4    return;
5}

À partir de là, PAO examine la commande exécutée et sélectionne le driver correspondant :

1$starter = match (basename($argv[0] ?? '')) {
2    'pest'    => new Drivers\Pest\Starter,
3    'phpunit' => new Drivers\Phpunit\Starter,
4    // ...
5};

Pour les runners de tests, PAO évite de parser la sortie terminal. PHPUnit, Paratest et Pest ont déjà le vrai résultat en interne. Pour PHPUnit, PAO injecte l'option --no-output. Pour Pest et Paratest, PAO silenciait la progression et laisse le runner s'exécuter normalement.

Au moment du shutdown, PAO capture le résultat de test directement depuis la facade de résultat de PHPUnit et construit le JSON depuis les données réelles :

1$result = PHPUnit\TestRunner\TestResult\Facade::result();

Pour Paratest, PAO utilise un runner wrapper pour que les résultats des workers parallèles soient fusionnés avant que la réponse finale soit écrite.

Pour PHPStan et Rector, PAO s'appuie sur les modes JSON natifs des outils plutôt que de parser leur sortie humaine :

1$_SERVER['argv'][] = '--error-format=json';
2$_SERVER['argv'][] = '--no-progress';

Pour les commandes Artisan, le service provider de PAO est auto-découvert dans les applications Laravel. Quand un agent est détecté, il lie l'OutputStyle de Laravel à l'implémentation de PAO et désactive la décoration Symfony Console au démarrage des commandes :

1$this->app->bind(OutputStyle::class, PaoOutputStyle::class);
2 
3$events->listen(CommandStarting::class, function (CommandStarting $event): void {
4    $event->output->setDecorated(false);
5});

Vos commandes Artisan continuent d'utiliser les mêmes APIs console, pendant que PAO nettoie la sortie à la frontière.

Disponible par défaut dans les nouvelles applications Laravel

Les nouvelles applications Laravel incluent désormais Laravel PAO automatiquement. Aucun fichier de configuration à publier, aucune installation requise.

Si vous souhaitez ajouter PAO à une application Laravel existante ou à un projet PHP standalone, installez-le avec Composer :

1composer require laravel/pao --dev

PAO fonctionne avec Laravel 12 et supérieur, PHP 8.3 et supérieur, et peut aussi être utilisé dans des projets PHP sans Laravel qui utilisent les outils supportés via l'autoloader de Composer.

Laravel a toujours soigné les détails qui rendent le développement fluide : des pages d'erreur claires, une sortie console expressive, des valeurs par défaut bien pensées, des outils qui maintiennent la concentration. Alors que les agents deviennent une partie de ce workflow, ils ont besoin du même niveau de soin. Laravel PAO garde le terminal beau pour les humains et rend la sortie des commandes plus facile à comprendre, résumer et exploiter pour les agents.

Source : https://github.com/laravel/pao

Écrit par

Ludovic Guénet

software engineer • mentor • bassist