Aller au contenu principal
Retour au blog

Pipelines RTK sur PHP : ce qui marche et ce qui coûte

rtk:posthook compresse Rector en une ligne, en coupant le milieu du diff. Moteur de pipelines, pertes par méthode et règle de garde testée sur une stack PHP.

Flavien Métivier · 7 min de lecture
Sommaire · 7 parties

Une ligne suffit : extends = "rtk:posthook". La sortie de Rector passe de 33 326 à 5 767 octets, celle de PHP-CS-Fixer de 25 362 à 5 602. Le gain est réel. Le problème, c'est ce qui disparaît. La chaîne appliquée finit par la méthode cap : au-delà de 300 lignes, elle garde les 50 premières et les 200 dernières. Sur Rector, le milieu coupé est justement le diff que l'agent devait relire.

Mon verdict d'abord : le moteur de pipelines de RTK est bien conçu, et sur une stack PHP il reste optionnel. Une fois les sorties sensibles exclues, le gain mesuré devient faible. Le levier principal reste ailleurs, dans la configuration et les filtres du projet. Si tu veux quand même l'activer, voici comment le faire sans perdre d'information, et ce que je n'ai pas réussi à valider.

Une précision sur les chiffres : RTK 1.1.0, projet Symfony de démo, un seul run. J'ai testé rtk:posthook en envoyant un payload simulé à rtk hook claude avec de vraies sorties d'outils, pas dans une session Claude Code. Le chemin complet du hook n'est donc pas validé en conditions réelles.

Qu'est-ce qu'un pipeline RTK, et en as-tu besoin ?

Un pipeline est un fichier TOML qui dit quand RTK agit, sur quoi, et ce qu'il fait. Depuis la 1.0, le comportement de RTK est lui-même écrit dans cette grammaire : rtk pipeline show rtk:default l'affiche. Si tu n'écris rien, rien ne change, et seul le hook PreToolUse sur Bash reste enregistré, comme dans l'installation de départ. Tes filtres restent dans filters.toml et tes préférences dans config.toml.

La nouveauté utile tient en un point : compresser la sortie d'une commande que le hook n'a pas réécrite. Un filtre ne s'applique qu'à une commande que RTK exécute lui-même. rtk:posthook agit après coup, via le hook PostToolUse et le champ updatedToolOutput de Claude Code, qui remplace ce qui est envoyé au modèle. L'outil a déjà tourné à ce moment-là, et l'OpenTelemetry de Claude Code capture la sortie d'origine. Si le mécanisme des hooks t'est moins familier, commence par les garde-fous déterministes.

Comment lire un fichier pipeline ?

Le fichier utilisateur est ~/.config/rtk/pipeline.toml, le fichier projet .rtk/pipeline.toml, soumis à approbation comme les filtres. La position d'une règle donne trois informations, dans cet ordre :

  • Le site : hook, dans l'agent, ou proxy, entre l'agent et l'API.
  • L'événement : before_tool, after_tool ou request.
  • Le sujet : shell, read, edit, search, web, mcp…

La première règle qui correspond gagne, sauf si elle porte continue = true. L'ordre est projet, utilisateur, hérité. Le moteur distingue aussi deux régimes en cas de version incompatible : une règle de compression inconnue est ignorée avec un avertissement, une règle de contrôle (deny, route, rewrite, passthrough) invalide fait refuser le fichier. Une protection ne peut donc pas sembler active alors qu'elle ne l'est pas.

Que perd-on avec rtk:posthook et la chaîne term ?

Sur le sujet shell, rtk:posthook applique la chaîne term aux commandes non réécrites : ansi, progress, dedup, base64-elide, puis cap. rtk methods list indique ce que chaque méthode perd.

  • Sans perte : ansi, dedup.
  • Avec perte, récupérable via rtk recall <hash> : progress, cap.
  • Avec perte, sans retour : base64-elide, qui remplace les longs blocs base64 par leur taille.

Sur mes sorties réelles, simulation de hook :

  • Rector --dry-run : de 33 326 à 5 767 octets.
  • PHP-CS-Fixer --dry-run --diff : de 25 362 à 5 602 octets.
  • bin/console debug:container : de 81 788 à 41 494 octets.
  • Psalm : de 7 373 à 6 435 octets.
  • PHPUnit avec deux échecs : de 1 058 à 1 017 octets, hash de récupération compris.
  • composer audit et composer install : aucun remplacement, sortie sous le seuil de cap.

Les deux premiers chiffres sont trompeurs. cap ne sait pas ce qu'est un diff : il coupe au milieu. La sortie complète reste accessible, mais l'agent doit la redemander, ce qui fait un tour de plus et réintroduit les octets économisés. Dans une session réelle sur PHPStan, autre filtre mais même logique, récupérer une sortie élidée a renvoyé 29 007 octets de JSON au modèle.

Votre équipe utilise Claude Code ?

Formation intra sur vos projets réels : de la demi-journée à 2 jours, 6 devs max.

Voir les formats →

Comment protéger les sorties PHP à lire en entier ?

Avec une règle passthrough placée avant la règle héritée. Comme tes règles passent avant celles de rtk:posthook, ceci suffit :

bash
# ~/.config/rtk/pipeline.toml
schema_version = 1
[pipeline]
extends = "rtk:posthook"

[[hook.after_tool.shell]]
name   = "php-verbatim"
when   = { command_matches = "(rector|php-cs-fixer|composer (audit|outdated)|doctrine:migrations|debug:|bin/phpunit)" }
action = "passthrough"

Testé : rtk pipeline validate accepte le fichier, explain annonce le passthrough, et la simulation ne remplace plus ni Rector ni debug:container. Psalm reste compressé, de 13 %, grâce à des méthodes sans perte. Voilà le constat honnête : une fois ces commandes protégées, il reste peu à gagner. La règle est volontairement large, à toi de la resserrer si debug: attrape trop de choses.

Comment tester un pipeline sans risque ?

En mode shadow : la règle décide et enregistre, mais n'émet rien. Tu lis ensuite ce qu'elle aurait économisé sur tes vraies commandes.

bash
[override.term-default]
shadow = true
bash
rtk pipeline validate    # syntaxe, conflits, hooks manquants
rtk pipeline explain --tool Bash --command "vendor/bin/rector process --dry-run"
rtk gain --shadow        # term-default  1 calls  246 saved (13%) sur mon test
  • Le hook manquant : tant que rtk init -g n'a pas été relancé, validate signale hook needed: PostToolUse hook missing, et la règle ne reçoit rien. Lance d'abord rtk init -g --dry-run : la commande écrit dans CLAUDE_CONFIG_DIR s'il est défini.
  • Le piège de bench : rtk pipeline bench sur mon composer.lock annonce 97,8 % d'économie. Il passe le fichier par la chaîne shell, pas par ce que fait une lecture via Read. Ce chiffre ne vaut rien pour ce cas.

Qu'est-ce que je ne recommande pas, ou n'ai pas validé ?

  • La compression de composer.lock : une règle basename_in avec la méthode lockfile se valide et explain la montre, mais je n'ai constaté aucun remplacement sur mon payload simulé de Read. Je ne la publie donc pas comme fonctionnelle. La documentation signale en outre que réécrire une lecture peut casser un Edit ultérieur (W021).
  • Le proxy : rtk:proxy s'intercale via ANTHROPIC_BASE_URL sur 127.0.0.1:8080 et relaie tes identifiants. La documentation elle-même indique que son cache-align est sans effet avec Claude Code, qui pose ses propres points de cache. L'idée qu'il ne casse pas le cache reste une affirmation de l'éditeur, que je n'ai pas mesurée.
  • route : le moteur peut déléguer une tâche à un modèle moins cher, y compris Claude via provider = "anthropic". Je ne l'ai pas testé.
  • L'édition rtk-oss : si tu as choisi la version Apache seule, tout cet article est sans objet. Elle n'a ni rtk pipeline ni rtk methods, et pipeline.toml y reste inerte. Hook, filtres, gain et recall y sont présents.

Faut-il activer les pipelines sur un projet Symfony ?

Pas par défaut. Commence par ce qui rapporte sans perte : sur mon banc, le filtre Composer corrigé fait passer une installation de 2 504 à 85 tokens estimés, sans le moteur. Il reste trois actions si tu veux évaluer le posthook sur ton projet :

  • Écris php-verbatim avec tes propres commandes à lire en entier.
  • Active term-default en shadow, relance rtk init -g après un --dry-run.
  • Lis rtk gain --shadow après quelques jours de travail. Si le gain ne justifie pas un hook de plus sur chaque commande, supprime le fichier.

Ces réglages viennent d'un projet de démo : sur ta base de code, seules tes propres commandes diront ce que RTK change. La formation intra travaille sur vos projets réels, et c'est là que ces essais prennent tout leur intérêt.

Cet article vous a été utile ? Partagez-le.

Portrait de Flavien Métivier, fondateur de The Bearded Bear : barbe longue, lunettes, sur fond sombre

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours

À lire ensuite

Votre équipe utilise Claude Code ?

Formation intra sur vos projets réels : de la demi-journée à 2 jours, 6 devs max.

Newsletter Bear Bytes

Veille Claude Code, Symfony et PHP, retours d'expérience terrain et conseils techniques, directement dans votre boîte mail.