Bon la on a un truc obscur, ./vendor/bin/php-parse. Ce petit binaire qui traîne dans vos projets Symfony comme un invité surprise à une soirée où personne ne sait vraiment pourquoi il est là. Pourtant, contrairement à certains outils de votre vendor/ qui ne servent qu’à gonfler votre composer.lock (je te regarde, symfony/polyfill-*), php-parse a une utilité bien réelle. Et non, ce n’est pas juste un prétexte pour faire joli dans votre bin/.
php-parse, ou l’art de disséquer du PHP sans scalpel
Derrière ce nom sobre se cache un outil qui fait une chose et une seule : parser du code PHP pour en extraire l’Abstract Syntax Tree (AST). L’AST, c’est cette représentation structurée de votre code que les machines adorent et que les humains fuient comme la peste. Imaginez un arbre généalogique, mais où chaque nœud est une instruction, une variable, ou une accolade mal placée. php-parse vous permet de générer cet arbre, de le manipuler, ou simplement de le regarder avec des yeux écarquillés en vous demandant comment diable votre code peut être aussi laid sous le capot.
Techniquement, php-parse est un wrapper autour de la fonction php-parse de la bibliothèque nikic/php-parser, une dépendance de Symfony (via symfony/console, entre autres). Son rôle ? Vous éviter d’écrire vous-même un script qui charge cette bibliothèque et qui fait le sale boulot à votre place. Parce que, soyons honnêtes, personne n’a envie de réinventer la roue, surtout quand elle est déjà bien graissée et qu’elle sent le PHP frais.
À quoi ça sert concrètement ?
Si vous vous demandez dans quels cas utiliser php-parse, voici quelques scénarios où il brille (ou du moins, où il évite de vous faire perdre des cheveux) :
- Analyse statique avancée : Besoin de vérifier que toutes vos classes implémentent bien une interface ? Ou que vos méthodes respectent une convention de nommage ?
php-parsepeut parcourir l’AST pour vous donner des réponses précises, sans se fier à des regex approximatives qui vous feront pleurer. - Refactoring automatisé : Remplacer toutes les occurrences d’une méthode dépréciée par sa nouvelle version ? Modifier dynamiquement des annotations Doctrine ? Avec
php-parse, vous pouvez manipuler l’AST pour réécrire du code sans tout casser (en théorie). - Génération de documentation : Extraire des métadonnées depuis votre code pour générer une doc technique ou un rapport ? L’AST est une mine d’or pour ça, à condition de savoir creuser.
- Outils maison : Vous avez un script qui vérifie que vos contrôleurs Symfony ne font pas n’importe quoi ?
php-parsepeut vous aider à le rendre plus robuste en analysant le code plutôt qu’en jouant aux devinettes avec desgrep.
Un exemple concret ?
Voici comment afficher l’arbre syntaxique d’un contrôleur PHP :
$ ./vendor/bin/php-parse --dump --with-positions src/Controller/MyController.php ==> Node dump: array( 0: Stmt_Namespace( name: Name( name: App\Controller ) stmts: array( 0: Stmt_Class( name: Identifier( name: MyController ) ... ) ) ) )
Ici, --dump affiche l’AST sous une forme relativement lisible, tandis que --with-positions ajoute les numéros de lignes et les positions des différents éléments. « Relativement lisible » reste évidemment une notion très personnelle : après 200 lignes de Stmt_Expression, même votre IDE commence à vous juger.
Si vous utilisez plutôt l’option --pretty-print, l’outil reconstruit du code PHP à partir de l’AST :
$ ./vendor/bin/php-parse --pretty-print src/Controller/MyController.php
Le résultat ressemble fortement au fichier d’origine, avec une mise en forme normalisée. Cela peut paraître inutile au premier abord : vous donnez du PHP à un outil, il vous rend du PHP, et tout le monde rentre chez soi. Mais cette fonctionnalité devient intéressante après avoir modifié l’AST dans un script. C’est justement ainsi que fonctionnent de nombreux outils de refactoring automatique.
Ce n’est pas vraiment un outil Symfony
Même si vous rencontrez souvent php-parse dans un projet Symfony, il ne fait pas partie du framework. Le binaire est fourni par le package nikic/php-parser. Celui-ci peut avoir été installé directement ou être arrivé discrètement avec un outil comme PHPStan, Rector ou une autre dépendance d’analyse de code.
Pour savoir qui l’a invité dans votre projet, Composer peut mener l’enquête :
$ composer why nikic/php-parser
Vous obtiendrez alors la liste des packages qui en dépendent. C’est toujours instructif de découvrir qu’un petit outil installé « juste pour tester » a ramené avec lui la moitié de Packagist.
Tester une version précise de PHP
Autre fonction pratique : php-parse peut analyser un fichier en ciblant une version particulière du langage. Par exemple, pour vérifier comment le parseur interprète du code destiné à PHP 8.3 :
$ ./vendor/bin/php-parse --version=8.3 src/Service/PaymentService.php
Attention cependant : cela ne remplace pas une vraie exécution avec la version concernée, ni un outil complet de compatibilité. Le parseur contrôle surtout la structure syntaxique. Il ne va pas vous avertir qu’une extension manque sur le serveur de production, que votre configuration PHP date du paléolithique ou que Gérard a encore modifié le php.ini directement dans le conteneur.
Du JSON pour les machines courageuses
Si votre objectif est d’exploiter le résultat dans un autre script, l’option --json-dump produit une représentation JSON de l’AST :
$ ./vendor/bin/php-parse --json-dump src/Entity/Product.php > product-ast.json
Ce format est pratique pour alimenter un outil externe, effectuer des comparaisons ou inspecter le code avec autre chose que PHP. Le fichier obtenu peut toutefois devenir gigantesque. Une classe Doctrine avec quelques attributs, des relations et deux ou trois méthodes suffit parfois à produire un roman russe composé exclusivement d’accolades.
Pourquoi ne pas utiliser simplement une regex ?
Parce qu’une regex voit du texte, alors qu’un parseur comprend la structure du langage. Chercher class avec grep fonctionne jusqu’au jour où le mot apparaît dans un commentaire, une chaîne de caractères, une classe anonyme ou une construction que votre expression régulière n’avait pas prévue.
L’AST permet de distinguer une classe, une méthode, un appel de fonction, un attribut PHP, une constante ou une variable. C’est plus verbeux, certes, mais aussi nettement moins fragile. Les regex restent excellentes pour remplacer une virgule dans trois fichiers. Pour refactorer 400 classes Symfony en production, elles ressemblent davantage à une tronçonneuse lancée dans une bijouterie.
Un outil de diagnostic, pas une baguette magique
php-parse est surtout utile pour explorer, comprendre et diagnostiquer. Le binaire permet de voir rapidement comment nikic/php-parser interprète un fichier, mais les transformations sérieuses nécessitent généralement un script PHP utilisant directement la bibliothèque, ses visiteurs de nœuds et son système de pretty-printing.
Autrement dit, vous n’allez probablement pas lancer php-parse tous les matins entre votre café et votre premier git pull. Mais le jour où vous devrez comprendre pourquoi Rector refuse une construction, inspecter un attribut, tester la syntaxe d’une nouvelle version de PHP ou fabriquer un analyseur maison, vous serez content de savoir pourquoi cet étrange exécutable squatte votre dossier vendor/bin.
Conclusion : obscur, mais loin d’être inutile
php-parse fait partie de ces outils que l’on ignore pendant des années avant de découvrir qu’ils constituent la plomberie invisible d’une bonne partie de l’écosystème PHP moderne. PHPStan, Rector et de nombreux outils d’analyse ou de transformation reposent sur le même principe : transformer votre code en une structure que la machine peut comprendre sans avoir à l’exécuter.
Vous pouvez donc continuer à ne jamais lancer directement ./vendor/bin/php-parse. Personne ne viendra retirer votre certification Symfony. Mais au moins, vous savez maintenant ce qu’il fait, pourquoi il est là, et surtout pourquoi analyser du PHP avec une regex reste une excellente façon de transformer un petit refactoring tranquille en incident de production.