Configurer Xdebug

Dans votre terminal local, ouvrez le fichier .magento.app.yaml dans un éditeur de texte.

Dans la section runtime, sous extensions, ajoutez xdebug. Par exemple :

runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug

Enregistrez vos modifications dans le fichier .magento.app.yaml et quittez l’éditeur de texte.

Ajoutez, validez et envoyez les modifications pour redéployer l’environnement.

git add .magento.app.yaml

git commit -m "add xdebug"

git push origin <environment-ID>

Dans votre projet PhpStorm, ouvrez le panneau Paramètres.

• macOS—Sélectionnez PhpStorm > Settings.
• Windows/Linux : Sélectionnez Fichier > Paramètres.

Dans le panneau Paramètres, développez la section PHP et cliquez sur Serveurs.

Cliquez sur + pour ajouter une configuration de serveur. Le nom du projet est en gris en haut.

[Facultatif] Configurez les paramètres suivants pour la nouvelle configuration du serveur. Voir Aucun serveur de débogage configuré dans la documentation de PHPStorm.

• Nom : saisissez le même nom que le nom d'hôte. Cette valeur doit correspondre à la valeur de la variable PHP_IDE_CONFIG dans les commandes Debug CLI pour utiliser l’interface de ligne de commande à des fins de débogage.
• Hôte : saisissez le nom d'hôte.
• Port—Saisissez 443.
• Debugger : sélectionnez Xdebug.

Sélectionnez Utiliser les mappages de chemin. Dans le volet Fichier/Répertoire, la racine du projet du serverName s’affiche.

Dans la colonne Chemin d’accès absolu sur le serveur, cliquez sur l’icône Modifier et ajoutez un paramètre en fonction de l’environnement.

• Pour tous les environnements de démarrage et les environnements d’intégration Pro, le chemin d’accès distant est /app.

• Pour les environnements d’évaluation et de production Pro :

  • Production : /app/<project_code>/
  • Évaluation : /app/<project_code>_stg/

Remplacez le port Xdebug par 9000,9003 ou limitez-le à 9000 dans le panneau PHP > Debug > Xdebug > Debug Port.

Cliquez sur Appliquer.

Ouvrez l'application PHPStorm et cliquez sur Add Configuration dans le coin supérieur droit de l'écran.

Cliquez sur Add new run configuration.

Sélectionnez l’option PHP Remote Debug .

• Saisissez un nom unique, mais reconnaissable.
• Cochez la case Filter debug connection by IDE key** .
• Sélectionnez le serveur que vous avez créé dans la section précédente. Si vous ne l’avez pas encore créé, vous pouvez le faire maintenant, mais reportez-vous à cette partie du guide de configuration.
• Dans le champ de texte IDE key(session id), saisissez PHPSTORM en majuscules. Nous l’utiliserons dans d’autres parties de la configuration. Il est donc important de conserver la même chose. Si vous choisissez une autre chaîne, vous devez vous rappeler de l’utiliser ailleurs dans le processus d’installation et de configuration.

Cliquez sur Apply > OK.

Ouvrez un terminal.

Utilisez SSH pour établir la connexion.

ssh -R 9000:localhost:9000 <ssh url>

Utilisez l’option -v (verbose) afin que chaque fois qu’un socket est connecté au port en cours de transfert, il s’affiche dans le terminal.

Si une erreur « impossible de se connecter » ou « impossible d'écouter le port sur la télécommande » s'affiche, une autre session SSH active peut persister sur le serveur qui occupe le port 9000. Si cette connexion n’est pas utilisée, vous pouvez l’arrêter.

Utilisez SSH pour vous connecter à l’environnement d’intégration, d’évaluation ou de production distant.

Consultez la liste des sessions SSH : who

Afficher les sessions SSH existantes par utilisateur. Veillez à ne pas affecter un utilisateur autre que vous-même !

• intégration : les noms d’utilisateur sont similaires à dd2q5ct7mhgus
• Évaluation : les noms d’utilisateur sont similaires à dd2q5ct7mhgus_stg
• Production : les noms d’utilisateur sont similaires à dd2q5ct7mhgus

Pour une session utilisateur plus ancienne que la vôtre, recherchez la valeur du pseudo-terminal (PTS), telle que pts/0.

Interrompt l’ID de processus (PID) correspondant à la valeur PTS.

ps aux | grep ssh
kill <PID>

Exemple de réponse :

dd2q5ct7mhgus        5504  0.0  0.0  82612  3664 ?      S    18:45   0:00 sshd: dd2q5ct7mhgus@pts/0

Pour mettre fin à la connexion, saisissez une commande kill avec l'ID de processus (PID).

kill 3664

Si vous ne l’avez pas déjà fait, téléchargez Putty.

Démarrez Putty.

Dans le volet Catégorie, cliquez sur Session.

Saisissez les informations suivantes :

• Champ Nom d’hôte (ou adresse IP) : saisissez l’URL SSH de votre serveur Cloud
• Champ Port : saisissez 22

Dans le volet Catégorie, cliquez sur Connexion > SSH > Tunnels.

Saisissez les informations suivantes :

• Port Source champ : saisissez 9000
• Champ Destination : saisissez 127.0.0.1:9000
• Cliquez sur Distant

Cliquez sur Ajouter.

Dans le volet Catégorie, cliquez sur Session.

Dans le champ Sessions enregistrées, saisissez un nom pour ce tunnel SSH.

Cliquez sur Enregistrer.

Pour tester le tunnel SSH, cliquez sur Charger, puis sur Ouvrir.

Si une erreur « impossible de se connecter » s’affiche, vérifiez les points suivants :

• Tous les paramètres Putty sont corrects
• Vous exécutez Putty sur la machine sur laquelle se trouvent vos clés SSH Adobe Commerce privées sur l’infrastructure cloud

Ouvrez un terminal.

Nettoyez toutes les sessions SSH pour chaque nœud web du cluster.

ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'

Configurez le tunnel SSH pour Xdebug pour chaque nœud web du cluster.

ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud

Activer le débogage à distance ; visitez le site dans le navigateur et ajoutez ce qui suit à l’URL où KEY est la valeur de xdebug_key.

?XDEBUG_SESSION_START=KEY

Cette étape définit le cookie qui envoie les requêtes du navigateur pour déclencher Xdebug.

Terminez le débogage avec Xdebug.

Lorsque vous êtes prêt à mettre fin à la session, utilisez la commande suivante pour supprimer le cookie et terminer le débogage via le navigateur dans lequel KEY est la valeur de xdebug_key.

?XDEBUG_SESSION_STOP=KEY

SSH dans le serveur que vous souhaitez déboguer à l’aide des commandes de l’interface de ligne de commande.

Créez les variables d’environnement suivantes :

export XDEBUG_CONFIG='PHPSTORM'

export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"

Ces variables sont supprimées à la fin de la session SSH.

Commencer le débogage

Dans les environnements de démarrage et les environnements d’intégration Pro, exécutez la commande de l’interface de ligne de commande pour déboguer.
Vous pouvez ajouter des options d’exécution, par exemple :

php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean

Sur les environnements d'évaluation et de production Pro, vous devez spécifier le chemin d'accès au fichier de configuration PHP Xdebug lors du débogage des commandes de l'interface de ligne de commande, par exemple :

php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean

Dans le menu Extension, cliquez sur Déboguer pour activer.

Cliquez avec le bouton droit de la souris, sélectionnez le menu d'options, puis définissez la touche IDE sur PHPSTORM.

Installez le client Xdebug sur le navigateur. Configurez et activez-le.

Créez un tunnel SSH vers le serveur cloud.

Installez l’extension Xdebug Helper à partir du magasin Chrome.

Activez l’extension dans Chrome, comme illustré ci-dessous.

Dans Chrome, cliquez avec le bouton droit sur l’icône d’assistance verte dans la barre d’outils de Chrome.

Dans le menu pop-up, cliquez sur Options.

Dans la liste IDE Key, cliquez sur PhpStorm.

Cliquez sur Enregistrer.

Ouvrez votre projet PhpStorm.

Dans la barre de navigation supérieure, cliquez sur l’icône Commencer à écouter.

Si la barre de navigation n’est pas affichée, cliquez sur Affichage > Barre de navigation.

Dans le volet de navigation PhpStorm, double-cliquez sur le fichier PHP à tester.

Utilisez SSH pour vous connecter à l’environnement distant.

Compressez les fichiers.

tar -czf /tmp/<file-name>.tgz <directory list>

Par exemple, pour compresser uniquement le répertoire vendor :

tar -czf /tmp/vendor.tgz vendor

Sur votre environnement local, utilisez PhpStorm pour compresser les fichiers.

cd <phpstorm project root dir>

rsync <SSH-URL>:/tmp/<file-name>.tgz .

tar xzf <file-name>.tgz