Aller au contenu

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.worktree gé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:trust joué 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 :

docker ps --filter "name=kirexo-ticket-185" --format '{{.Names}}'

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_PORT de ce worktree ;
  • cocher Can accept external connections.
grep XDEBUG_CLIENT_PORT .env.worktree

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
grep PHP_IDE_CONFIG .env.worktree     # PHP_IDE_CONFIG='serverName=ticket-185'

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) :

# .env.worktree — clé jamais réécrite par wt:up
XDEBUG_MODE='develop,debug'
docker compose up -d php     # côté hôte, ou : castor wt:up 185

Pour un besoin ponctuel en CLI — aucune recréation, aucun impact sur le serveur web :

docker compose exec -e XDEBUG_MODE=develop,debug php castor console app:…

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 :

  1. le mapping de l'interpréteur (étape 3) pointe bien sur /app ;
  2. le Server existe et porte le mapping (étape 6, case Use path mappings) ;
  3. le nom du Server est exactement celui de PHP_IDE_CONFIG :

    grep PHP_IDE_CONFIG .env.worktree
    

    Un serverName qui 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 :

grep XDEBUG_CLIENT_PORT .env.worktree   # dans chaque worktree, valeurs distinctes attendues

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 :

docker compose exec php getent hosts host.docker.internal

La valeur rendue doit être celle de WT_GATEWAY_IP :

grep WT_GATEWAY_IP .env.worktree

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é :

docker network inspect kirexo-ticket-185 --format '{{(index .IPAM.Config 0).Gateway}}'

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