Quand on utilise DDEV avec Mutagen pour un projet PHP, on exclut généralement le dossier vendor de la synchronisation pour des raisons de performance. C’est une bonne pratique, mais elle pose un problème : comment modifier rapidement un fichier du vendor pour débugger sans devoir utiliser Vim dans le container ?
Le problème
Sur mon projet, j’utilise DDEV avec Mutagen. Pour éviter des temps de synchronisation trop longs, le dossier vendor n’est pas suivi par Mutagen. Cependant, j’ai régulièrement besoin de modifier des fichiers dans le vendor pour débugger : ajouter des dump(), tracer l’exécution du code, ou tester des modifications temporaires.
Jusqu’ici, je devais ouvrir un terminal, entrer dans le container avec ddev ssh, éditer le fichier avec Vim, puis sauvegarder et quitter. C’est fastidieux, surtout quand on fait plusieurs allers-retours entre le code et le débug. L’idéal serait de pouvoir modifier le fichier directement dans PHPStorm et que la modification soit automatiquement répercutée dans le container.
La solution : File Watcher dans PHPStorm
PHPStorm propose une fonctionnalité appelée File Watchers qui permet d’exécuter une commande automatiquement lors de la modification d’un fichier. On va l’utiliser pour synchroniser les fichiers du vendor vers le container DDEV.
S’assurer que le vendor est indexé
Par défaut, PHPStorm exclut le dossier vendor de l’indexation. Les fichiers exclus n’apparaissent pas dans la configuration des scopes et ne peuvent pas déclencher de File Watcher.
Pour vérifier et corriger cela, ouvrez File → Project Structure (ou Cmd + ; sur Mac). Dans l’onglet Modules, vérifiez que le dossier vendor n’est pas marqué en orange (Excluded). Si c’est le cas, cliquez dessus et retirez l’exclusion. Alternativement, vous pouvez faire un clic droit sur le dossier vendor dans l’arborescence → Mark Directory as → Not Excluded.
Créer un scope pour le vendor
On ne veut pas que le File Watcher se déclenche pour tous les fichiers du projet, seulement pour ceux du vendor. Pour cela, on crée un scope personnalisé.
Allez dans Settings → Appearance & Behavior → Scopes, puis cliquez sur + pour créer un nouveau scope. Nommez-le Vendor et dans le pattern, entrez : file:vendor//*.
Configurer le File Watcher
Maintenant, créons le File Watcher qui va synchroniser les fichiers. Allez dans Settings → Tools → File Watchers, cliquez sur + et choisissez <custom>.
Donnez-lui un nom comme Sync vendor to DDEV. Pour le File type, sélectionnez PHP. Pour le Scope, choisissez le scope Vendor créé précédemment.
Dans Program, entrez /bin/bash. Dans Arguments, entrez la commande suivante :
-c "sleep 0.1 && cat '$FilePathRelativeToProjectRoot$' | ddev exec tee $FilePathRelativeToProjectRoot$ > /dev/null"Enfin, dans Working directory, entrez $ProjectFileDir$.
Configurer les options avancées
Dans la section Advanced Options du File Watcher, il est important de décocher « Auto-save edited files to trigger the watcher » et « Trigger the watcher on external changes ». Par contre, cochez « Trigger the watcher regardless of syntax errors ». Ces options évitent des déclenchements intempestifs et permettent de synchroniser même si le fichier contient des erreurs de syntaxe, ce qui est courant lors du débug.
Explication de la commande
Décortiquons la commande utilisée :
-c "sleep 0.1 && cat '$FilePathRelativeToProjectRoot$' | ddev exec tee $FilePathRelativeToProjectRoot$ > /dev/null"Le sleep 0.1 attend 100ms avant d’exécuter la commande. C’est crucial car PHPStorm déclenche le watcher pendant la sauvegarde du fichier. Sans ce délai, le fichier peut être vide ou partiellement écrit, causant une race condition.
Ensuite, cat '$FilePathRelativeToProjectRoot$' lit le contenu du fichier modifié. La variable PHPStorm $FilePathRelativeToProjectRoot$ donne le chemin relatif, par exemple vendor/symfony/http-kernel/HttpKernel.php.
Le contenu est ensuite envoyé via un pipe vers ddev exec tee $FilePathRelativeToProjectRoot$. La commande tee exécutée dans le container DDEV écrit le contenu reçu sur stdin vers le fichier spécifié. Le > /dev/null à la fin supprime la sortie standard de tee pour éviter de polluer la console.
Le délai de 100ms : résoudre la race condition
Sans le sleep 0.1, j’obtenais des fichiers vides dans le container. Le problème vient du fait que PHPStorm déclenche le File Watcher au moment où il commence à écrire le fichier sur le disque, pas quand l’écriture est terminée.
Un délai de 100ms s’est avéré être le bon compromis : assez long pour que le fichier soit complètement écrit, assez court pour ne pas ralentir le workflow.
Débugger en cas de problème
Si la synchronisation ne fonctionne pas, PHPStorm affiche une console avec les erreurs de la commande. Cela permet de comprendre rapidement ce qui ne va pas : chemin incorrect, problème de permissions, container non démarré, etc.
Vous pouvez aussi tester la commande manuellement dans un terminal pour vérifier qu’elle fonctionne :
cat 'vendor/symfony/http-kernel/HttpKernel.php' | ddev exec tee vendor/symfony/http-kernel/HttpKernel.php > /dev/nullConclusion
Cette solution permet de garder les avantages de performance de l’exclusion du vendor dans Mutagen, tout en ayant un workflow de débug fluide. On modifie le fichier dans PHPStorm avec toutes les fonctionnalités de l’IDE (coloration syntaxique, autocomplétion, navigation), on sauvegarde, et la modification est instantanément disponible dans le container.
Plus besoin de jongler entre l’IDE et Vim dans le terminal !
Laisser un commentaire