Brancher PhpStorm sur un worktree¶
Vous êtes développeur·se sur Kirexo, vous utilisez PhpStorm, et vous voulez éditer le code sur l'hôte tout en exécutant PHP, Composer, PHPUnit et Xdebug dans le conteneur du worktree. Cette recette couvre les sept réglages à faire une fois par worktree, puis les trois pannes silencieuses qu'un réglage manquant provoque.
Le projet s'ouvre nativement, comme n'importe quel dossier : le conteneur n'est qu'un interpréteur distant. On n'ouvre plus le projet « dans » le conteneur — c'est ce mode qui faisait construire à l'IDE une image jb-<hash>-uid par poste, jamais à jour et invisible de castor wt:list.
Prérequis¶
- Le worktree démarré côté hôte :
castor wt:up 185(cf. Créer et détruire un worktree). - Le fichier
.env.worktreegénéré à la racine du worktree — il porte les quatre valeurs à reporter dans l'IDE (XDEBUG_CLIENT_PORT,XDEBUG_CONFIG,PHP_IDE_CONFIG,WT_GATEWAY_IP). Contenu détaillé : Variables de worktree. castor cert:trustjoué une fois sur le poste, pour que la CA du proxy soit reconnue. Toutes les URLs du worktree passent alors sans avertissement.- Une fenêtre PhpStorm par worktree. L'isolation visuelle est native, et elle est nécessaire : le port de debug est propre à chaque worktree (étape 5).
Les libellés d'écran peuvent varier d'une version de PhpStorm à l'autre
Les chemins de réglages cités ci-dessous décrivent l'interface au moment de la rédaction. Ils n'ont pas pu être confrontés à la documentation JetBrains : jetbrains.com n'est pas dans l'allowlist du proxy de sortie du conteneur, et on demande l'ouverture d'un domaine plutôt que de la contourner.
Ce qui, en revanche, ne bouge pas : le comportement. C'est celui du protocole DBGp — un port d'écoute par fenêtre d'IDE, un path mapping pour résoudre les chemins du conteneur, un nom de serveur pour rattacher une session CLI à ce mapping. Si un libellé a changé, cherchez le réglage par sa fonction, pas par son intitulé.
Étape 1 — Ouvrir le worktree nativement¶
File > Open, sur le chemin hôte du worktree — par défaut <parent du dépôt principal>/kirexo-worktrees/ticket-185, ou la racine que vous avez fixée dans KIREXO_WORKTREES_DIR.
L'indexation se fait sur le système de fichiers de l'hôte, et git aussi : le fichier .git du worktree pointe en chemin absolu côté hôte vers le dépôt principal, et PhpStorm le suit sans rien de particulier.
Ne pas « rouvrir dans le conteneur »
L'IDE propose encore un mode où il s'exécute lui-même dans le conteneur, au lieu de s'y connecter. Ce mode construit sa propre image dérivée, jb-<hash>-uid, une par poste et par empreinte de configuration : elle ignore le docker compose build lancé depuis l'hôte, dérive silencieusement du Dockerfile du dépôt, et n'apparaît nulle part dans l'outillage du projet.
Le projet ne s'ouvre plus ainsi. Si un poste porte encore une telle surcouche, castor image:refresh la retire à son étape 3/4 — il n'en crée jamais.
Étape 2 — Déclarer l'interpréteur PHP du conteneur¶
Settings > PHP > CLI Interpreter, bouton … → From Docker, Vagrant, VM, WSL, Remote…, type Docker Compose :
| Champ | Valeur |
|---|---|
| Configuration files | compose.yaml et compose.override.yaml |
| Service | php |
| Lifecycle | Connect to existing container (docker compose exec) |
Surtout pas « Always start a new container »
Ce mode démarre une stack parallèle à chaque exécution, en plus de celle du worktree. Deux conséquences immédiates : les conteneurs et les volumes se dupliquent, et la stack ainsi créée n'empile pas compose.worktree.yaml — le fichier qui monte le git common dir dans le conteneur et qui n'est empilé que par les cibles castor wt:*. Plus aucune commande git ne fonctionne alors depuis l'intérieur.
« Connect to existing container » se contente d'entrer dans le conteneur que castor wt:up a démarré. C'est le seul mode correct ici.
Si l'IDE ne trouve pas le conteneur
Le nom du projet Compose d'un worktree vient de COMPOSE_PROJECT_NAME, écrite dans .env.worktree (kirexo-ticket-185). Un lanceur qui ne lit pas ce fichier retombe sur le basename du dossier et cherche donc les conteneurs d'un projet qui n'existe pas. Le nom réel se vérifie côté hôte :
La précédence exacte des noms de projet est décrite dans Les 16 clés du contrat.
Étape 3 — Le path mapping de l'interpréteur¶
Dans la configuration de l'interpréteur, section Path mappings : chemin hôte du worktree ↔ /app.
C'est le réglage qui casse tout sans un message d'erreur. Absent ou faux :
- PHPUnit tourne et rend ses résultats, mais les fichiers ne sont pas résolus ;
- les liens des stack traces pointent dans le vide ;
- aucun breakpoint n'est jamais atteint.
Rien dans l'interface ne signale l'anomalie : tout a l'air de fonctionner.
Étape 4 — Les tests : PHPUnit par interpréteur distant¶
Settings > PHP > Test Frameworks, ajouter un PHPUnit by Remote Interpreter :
| Champ | Valeur |
|---|---|
| Interpreter | celui de l'étape 2 |
| Path to script | /app/vendor/autoload.php |
| Default configuration file | /app/phpunit.dist.xml |
Les chemins sont ceux du conteneur : c'est là que vit vendor/.
La préparation de la base de test n'a rien de spécial à faire ici : tests/bootstrap.php enchaîne ses commandes Doctrine à chaque démarrage de PHPUnit, quel que soit le point d'entrée (cf. Exécuter les tests). L'IDE sert à itérer sur un test ; la référence avant de rendre la main reste castor all.
Étape 5 — Le port de debug, propre à ce worktree¶
Settings > PHP > Debug > Xdebug :
- Debug port : la valeur
XDEBUG_CLIENT_PORTde ce worktree ; - cocher Can accept external connections.
Le port 9003 (défaut d'Xdebug) est réservé au dépôt principal ; les worktrees allouent à partir de 9004. La valeur est figée au premier castor wt:up puis réutilisée telle quelle : votre configuration PhpStorm ne se désynchronise pas d'une relance à l'autre.
Deux fenêtres ne peuvent pas écouter le même port. La seconde n'écoutera pas, et la session de debug de l'un des deux worktrees ne s'ouvrira jamais.
Étape 6 — Un Server nommé exactement comme le worktree¶
Settings > PHP > Servers, créer un serveur :
| Champ | Valeur |
|---|---|
| Name | ticket-185 — identique à WT, donc à la valeur de PHP_IDE_CONFIG |
| Host | app.ticket-185.localhost |
| Port | 443 |
| Debugger | Xdebug |
| Use path mappings | coché — racine du projet hôte ↔ /app |
Le nommage n'est pas cosmétique : c'est lui qui relie une session CLI (PHPUnit, castor console) à un path mapping. Xdebug transmet le serverName porté par PHP_IDE_CONFIG, l'IDE cherche un Server de ce nom, et applique son mapping.
D'où deux mappings à renseigner, qui ne couvrent pas la même chose :
| Mapping | Ce qu'il couvre |
|---|---|
| celui de l'interpréteur (étape 3) | l'exécution — retrouver les fichiers lancés dans le conteneur |
| celui du Server (ici) | le debug — résoudre /app/src/… en <worktree hôte>/src/… quand une session s'ouvre |
Étape 7 — Activer Xdebug, puis déclencher une session¶
Xdebug est installé mais inerte par défaut (xdebug.mode = off dans frankenphp/conf.d/20-app.dev.ini) : l'activer en permanence coûte de la performance sur chaque exécution CLI.
Pour une campagne de debug — décommenter la clé libre dans .env.worktree, puis recréer le conteneur côté hôte (les variables d'environnement sont lues au démarrage ; un simple restart ne suffit pas) :
Pour un besoin ponctuel en CLI — aucune recréation, aucun impact sur le serveur web :
xdebug.mode ne se règle que par XDEBUG_MODE
XDEBUG_CONFIG=mode=develop,debug est silencieusement ignoré par Xdebug : aucune erreur, aucun log, le step-debugger reste simplement inerte. Détail : XDEBUG_MODE est la clé libre.
Le déclenchement se fait à la demande (xdebug.start_with_request = trigger dans l'INI de dev) — pas à chaque requête :
| Contexte | Déclencheur |
|---|---|
| CLI | XDEBUG_TRIGGER=1 castor console app:… |
| HTTP | l'extension navigateur d'aide Xdebug, ou ?XDEBUG_TRIGGER=1 dans l'URL |
Côté IDE, il reste à mettre l'écoute des connexions entrantes en marche avant de déclencher.
Ça ne marche pas ?¶
Trois modes de panne, tous silencieux — d'où l'ordre de vérification.
Tout tourne, aucun breakpoint n'est atteint¶
Symptôme : les tests passent, l'application répond, la session semble s'ouvrir, mais l'exécution ne s'arrête jamais. Les liens des stack traces ouvrent des fichiers vides ou rien du tout.
C'est un path mapping absent ou faux. Trois vérifications, dans cet ordre :
- le mapping de l'interpréteur (étape 3) pointe bien sur
/app; - le Server existe et porte le mapping (étape 6, case Use path mappings) ;
-
le nom du Server est exactement celui de
PHP_IDE_CONFIG:Un
serverNamequi ne correspond à aucun Server déclaré ne produit aucun avertissement : la session s'ouvre, le mapping n'est pas trouvé, le breakpoint n'est jamais atteint.
Le port est déjà pris par une autre fenêtre¶
Symptôme : le debug fonctionnait, il s'arrête de fonctionner quand une seconde fenêtre PhpStorm est ouverte — ou l'inverse, selon l'ordre de démarrage.
Un port ne peut être écouté que par une fenêtre. Vérifiez que chaque worktree a bien le sien :
Puis reportez la valeur dans Settings > PHP > Debug > Xdebug > Debug port de la fenêtre correspondante (étape 5). Le dépôt principal garde 9003.
host.docker.internal retombe sur 172.17.0.1¶
Symptôme : rien. Xdebug tente la connexion vers une adresse non routable et abandonne sans un mot.
Le réseau de la stack est en internal: true : aucune route par défaut n'y est posée, et l'IP de docker0 (172.17.0.1, ce que rend host-gateway) n'y est pas joignable. La seule adresse de l'hôte atteignable est la gateway du réseau de la stack, relevée par castor wt:up dans WT_GATEWAY_IP et injectée par extra_hosts.
Le contrôle, côté hôte :
La valeur rendue doit être celle de WT_GATEWAY_IP :
Si vous lisez 172.17.0.1, c'est un repli sur host-gateway : WT_GATEWAY_IP est vide ou périmée. Un castor wt:up 185 la relève sur le réseau réel et recrée le seul service php quand elle a changé (extra_hosts est figé à la création du conteneur). Contrôle croisé :
Le raisonnement complet — pourquoi cette IP est relevée et jamais calculée — est dans Aucune subnet n'est allouée.
Pour aller plus loin¶
- Les seize clés du contrat
.env.worktree(wt_managed_keys,infra/worktree/env.lib.sh), leurs défauts et leurs lecteurs : Variables de worktree. - Le cycle de vie d'un worktree et ses trois URLs : Créer et détruire un worktree.
- Le nommage
<service>.<worktree>.localhost, la CA locale et le cloisonnement réseau : Routage des worktrees : DNS, TLS et cloisonnement réseau. - Ce que le proxy de sortie autorise, et comment ouvrir un domaine : Ouvrir un domaine dans l'allowlist du proxy sortant.