Aller au contenu

Castor, l'autoloader du projet et la contrainte PHP

Kirexo fige la contrainte PHP de composer.json sur "php": "8.5.*" et interdit à Renovate d'y toucher. Ce n'est ni une préférence de style ni un oubli de maintenance : c'est ce qui empêche le task runner du projet de se rendre lui-même inutilisable, y compris pour se réparer.

Trois faits anodins qui, ensemble, tuent Castor

Le premier : le binaire castor embarque son propre PHP. Ce n'est pas le PHP du conteneur : celui de l'hôte tourne sur l'interpréteur qu'il transporte, mesuré en 8.5.6 pour la version figée par le projet (CASTOR_VERSION=v1.7.0 dans le Dockerfile, suivie par castor image:check-tools). Le poste de développement n'a d'ailleurs aucun PHP installé, c'est un invariant du projet — la version qui exécute castor.php côté hôte est donc toujours celle du binaire.

Le deuxième : castor.php charge délibérément l'autoloader du projet. Castor tourne avec son propre autoloader et ignorerait sinon les classes App\Castor\… — ToolsUpgrader pour image:upgrade-tools, BranchResolver pour wt:up. Le fichier fait donc, à la racine, un require_once __DIR__.'/vendor/autoload.php' quand celui-ci existe.

Le troisième : Composer génère un contrôle de plateforme à partir de la contrainte php. vendor/composer/platform_check.php, inclus par l'autoloader, compare PHP_VERSION_ID à la borne basse et tue le process si elle n'est pas atteinte.

Pris isolément, aucun de ces trois faits n'est discutable. Mis bout à bout avec une contrainte >=8.5.9, ils donnent ceci — sur n'importe quelle commande :

$ castor list
In autoload_real.php line 25:
  Composer detected issues in your platform: Your Composer dependencies require
  a PHP version ">= 8.5.9". You are running 8.5.6.

Rien du dépôt n'exige pourtant 8.5.9 : sur les paquets du lock, la contrainte PHP la plus haute est >=8.4.1. La borne venait uniquement de composer.json.

Ce qui rend cette panne particulière

Une dépendance cassée se répare avec l'outillage du projet. Ici, l'outillage est la victime. castor install, castor docker:up, castor wt:up — tout meurt sur la même ligne, avant d'avoir exécuté quoi que ce soit. Le seul chemin de sortie passe hors de Castor, ce que la règle « Castor est le task runner unique » n'avait pas prévu : corriger la contrainte, puis régénérer l'autoloader avec un docker compose run --rm --no-deps php composer install.

Et la panne ne se déclenche pas au moment où la contrainte change. Elle attend le premier composer install — un castor install après un git pull, ou le premier wt:up d'un worktree neuf. Entre les deux, un vendor/ déjà installé continue de fonctionner : la borne y est écrite dans un fichier généré, pas relue depuis composer.json. L'écart entre la cause et le symptôme peut donc se compter en semaines.

Pourquoi une correction manuelle ne suffisait pas

La contrainte avait déjà été assouplie à la main, dans un commit explicite (« assouplit la contrainte php à >=8.5 »). Elle a été refigée deux fois ensuite, par Renovate.

C'est mécanique : renovate.json porte "rangeStrategy": "bump" globalement, ce qui relève la borne basse de toute contrainte pour la coller à la dernière version publiée, et "automerge": true + "platformAutomerge": true, qui font passer la MR sans qu'un humain la regarde. À chaque patch de PHP, la borne remontait — >=8.5.7, puis >=8.5.8, puis >=8.5.9 — et le compte à rebours repartait.

Une règle qui n'existe que dans la tête du mainteneur n'est pas une règle : c'est une dette qui rejoue.

La forme retenue, et ce qu'elle borne

"php": "8.5.*" produit un contrôle de plateforme >= 8.5.0 && < 8.6.0. Le PHP de Castor (8.5.6) le franchit, celui du conteneur aussi.

Le choix de la mineure est délibéré. >=8.5 conviendrait au regard de la panne, mais laisserait passer une 8.6 alors que l'image de base est dunglas/frankenphp:1.12.7-php8.5-alpine : la contrainte cesserait de décrire ce sur quoi le projet tourne réellement. 8.5.* dit exactement cela — la mineure est un engagement, le patch n'en est pas un.

Le second volet est dans renovate.json, en dernière packageRule (une packageRule surcharge le rangeStrategy global, et la dernière règle qui matche l'emporte) :

{
  "matchManagers": ["composer"],
  "matchDepNames": ["php"],
  "rangeStrategy": "in-range-only"
}

in-range-only autorise Renovate à mettre à jour le lock sans jamais réécrire la contrainte. Le bot continue donc son travail sur PHP ; il ne peut simplement plus déplacer la borne.

Trois voies écartées

Neutraliser le contrôle de plateforme. Commenter la ligne require __DIR__ . '/platform_check.php'; dans vendor/composer/autoload_real.php fait disparaître le symptôme immédiatement. C'est un fichier généré et gitignoré : la rustine ne survit pas au premier composer install, ne se propage à aucun autre poste, et surtout masque durablement une régression réelle. Elle a existé dans le dépôt principal ; c'est ce qui explique que la panne n'y ait jamais été vue, alors qu'elle y dormait.

Ne plus charger l'autoloader du projet dans castor.php. Cela résoudrait le conflit en supprimant le pont — et avec lui les classes App\Castor\… que les cibles utilisent. Ce pont est ce qui permet d'extraire la logique décidable des cibles vers castor/src/, seul répertoire de Castor inclus dans le périmètre de couverture. Le supprimer ferait reculer la testabilité pour régler un problème de bornes de version.

Mettre à jour le binaire castor de chaque poste. Cela repousse la panne d'un cran sans la fermer : la contrainte pourrait de nouveau dépasser le PHP embarqué au prochain bump, et le remède dépendrait de la diligence de chaque développeur·se plutôt que d'un fichier versionné. La question redeviendra pertinente le jour où le projet exigera une fonctionnalité de PHP 8.6.

Le corollaire : Castor doit tourner sans vendor/

La même boucle guette ailleurs. castor wt:up est la cible qui amorce un checkout neuf — elle y installe les dépendances — et elle dépend de App\Castor\Worktree\BranchResolver, une classe qui vit dans vendor/… jusqu'à ce que wt:up l'ait installée. Sans précaution, la cible de bootstrap exigerait que le bootstrap ait déjà eu lieu.

D'où le repli de castor.php : quand vendor/autoload.php est absent, un autoloader minimal reproduit la règle PSR-4 App\Castor\ → castor/src/, et rien d'autre. Hors de ce namespace, un « class not found » reste le bon message et castor install le bon remède.

Les deux dispositifs disent la même chose : un outil dont le rôle est de réparer l'environnement ne doit jamais dépendre d'un environnement déjà réparé.

L'autre corollaire : ne jamais supprimer le vendor/ dont on dépend

Le repli précédent traite l'absence de vendor/ au démarrage. Il reste un cas où le vendor/ est là au démarrage et disparaît en cours de route : castor wt:destroy <ticket> lancé depuis le dossier de ce worktree.

C'est pourtant le geste nominal — on finit un ticket, on est dans son répertoire, on range. Mais git worktree remove --force efface le répertoire entier, fichiers ignorés par git compris, donc vendor/. Le processus vient de supprimer les fichiers dont il dépend, et il ne le sait pas : PHP ne charge une classe qu'au moment où il en a besoin. Tout ce qui était déjà en mémoire continue de fonctionner ; tout ce qui reste à charger est devenu une mine.

Le second fait de ce document aggrave le premier. L'autoloader du projet, chargé par castor.php, est enregistré en prepend : il passe devant celui du phar Castor pour tout ce qui commence par Symfony\, y compris pour les classes dont le phar aurait pourtant sa propre copie, intacte. Il n'y a donc pas de repli implicite sur le binaire.

Le résultat lu par l'utilisateur était le pire des trois possibles — un message exact mais trompeur :

✓ stack détruite (conteneurs, réseau, volumes)
✓ conf proxy retirée
✓ vhost RabbitMQ supprimé
✓ worktree git retiré

In ClassLoader.php line 576:
  Warning: include(…/ticket-101/vendor/…/Event/ConsoleErrorEvent.php):
  Failed to open stream: No such file or directory

La destruction a réussi — les quatre coches ne mentent pas. C'est l'épilogue de la commande qui tombe, avec un code de sortie non nul, et un message qui désigne un fichier de vendor/ là où la cause est « ce répertoire n'existe plus, et c'est moi qui l'ai supprimé ».

Pourquoi un inventaire de préchargement n'était pas une réponse

La première idée est de charger d'avance les classes concernées. Elle ne tient pas à l'usage, et on l'a vérifié en la poussant : réparer le répertoire de travail des sous-processus a déplacé la panne d'un cran, de ConsoleErrorEvent vers ConsoleTerminateEvent — que Symfony Console instancie après le retour de la tâche — puis vers OutputWrapper, que io()->success() charge à son premier appel. La frontière n'est pas dans le code de la cible : elle est dans la queue du framework, qui s'exécute quand la cible a fini de parler.

Une liste figée aurait donc dû inventorier le chemin d'exécution de Symfony Console jusqu'au dernier exit. Elle se périmerait au premier bump de symfony/console — et sa péremption ressemblerait trait pour trait au défaut d'origine : quatre coches vertes, puis un Failed to open stream. Un remède dont l'échec est indiscernable du symptôme qu'il traite n'en est pas un.

Le remède : changer de processus, pas de liste

La seule propriété qui ne demande aucun inventaire est structurelle : le processus qui supprime le vendor/ n'est pas celui qui en dépend. Quand wt:destroy constate qu'on l'appelle depuis le worktree qu'elle vise, elle se relance depuis le dépôt principal — qui porte le worktree, et ne peut donc pas être ce worktree — et s'efface immédiatement derrière son relais. La destruction se déroule dans un processus dont le vendor/ n'est pas menacé, et le code de sortie redevient celui de la destruction.

Deux détails portent tout le dispositif :

  • s'effacer, c'est exit(), jamais return. Rendre la main à Symfony Console suffirait à rejouer la panne : c'est elle qui dispatcherait ensuite ConsoleTerminateEvent, une classe encore froide dont le fichier a disparu. La commande n'a donc plus rien à afficher après le relais — pas même un message de succès, qui chargerait OutputWrapper ;
  • la comparaison « suis-je dans ce répertoire ? » est une question de segments, pas de chaînes. /…/ticket-10 est un préfixe textuel de /…/ticket-101 : un str_starts_with nu prendrait un worktree voisin pour le sien et relancerait une destruction depuis un dossier parfaitement sain. C'est ce que tranche App\Castor\Worktree\WorkingDirectory (castor/src/Worktree/WorkingDirectory.php), la seule partie décidable du correctif, et à ce titre la seule qui soit testable sans disque ni daemon Docker.

Ce que la même cause abîmait ailleurs : un contrôle muet

Le même lot corrige un second défaut, de la même famille mais d'une gravité différente, parce qu'il touchait un contrôle plutôt qu'un affichage.

En fin de course, wt:destroy vérifie qu'aucune conf proxy ne survit au worktree. Le chemin de ce fichier n'est jamais écrit en dur : il est rendu par une fonction de infra/proxy/proxy.lib.sh, sourcée depuis le checkout courant. Ce contrôle s'exécutant après le retrait du worktree, la lib n'existait plus : le source échouait, la sortie était vide, et le contrôle concluait « aucun résidu » sans avoir rien mesuré.

Une conf proxy survivante n'est pas un détail cosmétique : Caddy continue de router les trois URLs d'un worktree détruit vers un conteneur qui n'existe plus, et répond 502. La sonde censée l'annoncer disait le contraire. Une sonde muette est pire qu'une sonde absente — la seconde se remarque.

Le correctif est le même raisonnement appliqué aux données plutôt qu'au processus : tout ce qui doit être lu dans le worktree est lu avant qu'il ne disparaisse, et tout ce qui s'exécute après est ancré sur le dépôt principal.

Détail de ce que la commande affiche dans ce cas : castor wt:destroy.

Voir aussi