Documentation Commerce Guide de Commerce sur Cloud

Configurer Xdebug

Dernière mise à jour : 31 janvier 2025

Rubriques :
Cloud

Créé pour :

Administration
Développeur

Xdebug est une extension pour déboguer votre PHP. Bien que vous puissiez utiliser un IDE de votre choix, la procédure suivante explique comment configurer Xdebug et PhpStorm pour le débogage dans votre environnement local.

NOTE

Vous pouvez configurer Xdebug pour qu’il s’exécute dans l’environnement Cloud Docker à des fins de débogage local sans modifier la configuration de votre projet Adobe Commerce sur l’infrastructure cloud. Voir Configuration de Xdebug pour Docker.

Pour activer Xdebug, vous devez configurer un fichier dans votre référentiel Git, votre IDE et configurer le transfert de port. Vous pouvez configurer certains paramètres dans le fichier magento.app.yaml. Après modification, poussez les modifications Git sur tous les environnements de démarrage et les environnements d’intégration Pro pour activer Xdebug. Xdebug est déjà disponible dans les environnements d’évaluation et de production Pro.

Une fois configurée, vous pouvez déboguer les commandes de l’interface de ligne de commande, les requêtes web et le code. N’oubliez pas que tous les environnements d’infrastructure cloud sont en lecture seule. Clonez le code dans votre environnement de développement local pour effectuer le débogage. Pour les environnements d’évaluation et de production Pro, consultez instructions supplémentaires pour plus d’Xdebug.

Conditions requises

Pour exécuter et utiliser Xdebug, vous avez besoin de l’URL SSH pour l’environnement . Vous pouvez localiser les informations via le Cloud Console ou votre Cloud Onboarding UI.

Configurer Xdebug

Pour configurer Xdebug, procédez comme suit :

Utiliser une branche pour transmettre les mises à jour de fichiers
Activation Xdebug environnements
Configuration du serveur PHPStorm
Configurer le transfert de port

Prise en main d’une branche

Pour ajouter des Xdebug, Adobe recommande de travailler dans une branche de développement.

Activation de Xdebug dans votre environnement

Vous pouvez activer Xdebug directement dans tous les environnements de démarrage et les environnements d’intégration Pro. Cette étape de configuration n’est pas requise pour les environnements de production et d’évaluation Pro. Voir Débogage pour l’évaluation et la production pro.

video poster

https://video.tv.adobe.com/v/3437407?learn=on

Pour activer le Xdebug pour votre projet, ajoutez des xdebug à la section runtime:extensions du fichier .magento.app.yaml.

Pour activer 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>

Lorsqu’il est déployé dans des environnements de démarrage et des environnements d’intégration Pro, Xdebug est désormais disponible. Continuez à configurer votre IDE. Pour PhpStorm, voir Configuration de PhpStorm.

Configuration du serveur PhpStorm

video poster

https://video.tv.adobe.com/v/3437409?learn=on

L’IDE PhpStorm doit être configuré pour fonctionner correctement avec Xdebug.

Pour configurer PhpStorm afin qu’il fonctionne avec Xdebug :

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.

Créer la configuration PHPStorm Run/Debug

Cela permet à l’application de disposer des paramètres de débogage corrects pour gérer la requête de l’application Adobe Commerce.

video poster

https://video.tv.adobe.com/v/3437426?learn=on

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.

Configurer le transfert de port

video poster

https://video.tv.adobe.com/v/3437410?learn=on

Mappez la connexion XDEBUG du serveur à votre système local. Pour effectuer tout type de débogage, vous devez transférer le port 9000 de votre serveur Adobe Commerce on cloud infrastructure vers votre ordinateur local. Consultez l’une des sections suivantes :

Transfert de port sous Mac ou UNIX
Transfert de port sous Windows

Transfert de port sous Mac ou UNIX®

Pour configurer le transfert de port sur un environnement Mac ou UNIX®, procédez comme suit

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.

Pour résoudre les problèmes de connexion :

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

Transfert de port sous Windows

Pour configurer le transfert de port (tunneling SSH) sous Windows, vous devez configurer votre application de terminal Windows. Cet exemple montre comment créer un tunnel SSH à l’aide de Putty. Vous pouvez utiliser d'autres applications telles que Cygwin. Pour plus d’informations sur les autres applications, consultez la documentation fournisseur fournie avec ces applications.

Pour configurer un tunnel SSH sous Windows à l’aide de Putty :

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

Accès SSH aux environnements Xdebug

Pour lancer le débogage, effectuer la configuration, etc., vous avez besoin des commandes SSH pour accéder aux environnements. Vous pouvez obtenir ces informations via le Cloud Console et la feuille de calcul de votre projet.

Pour les environnements de démarrage et les environnements d’intégration Pro, vous pouvez utiliser la commande d’interface de ligne de commande magento-cloud suivante pour SSH dans ces environnements :

magento-cloud environment:ssh --pipe -e <environment-ID>

Pour utiliser Xdebug, SSH dans l’environnement comme suit :

ssh -R <xdebug listen port>:<host>:<xdebug listen port> <SSH-URL>

Par exemple,

ssh -R 9000:localhost:9000 pwga8A0bhuk7o-mybranch@ssh.us.magentosite.cloud

Débogage pour l’évaluation et la production professionnelles

NOTE

Sur les environnements d’évaluation et de production Pro, Xdebug est toujours disponible, car ces environnements disposent d’une configuration spéciale pour les Xdebug. Toutes les requêtes web normales sont acheminées vers un processus PHP dédié qui n'a pas de Xdebug. Par conséquent, ces requêtes sont traitées normalement et ne subissent pas de dégradation des performances lors du chargement de la Xdebug. Lorsqu’une requête web est envoyée avec la clé Xdebug, elle est acheminée vers un processus PHP distinct qui a Xdebug chargé.

Pour utiliser Xdebug spécifiquement sur l'environnement d'évaluation et de production Pro Plan, vous devez créer un tunnel SSH distinct et une session Web à laquelle vous avez uniquement accès. Cette utilisation diffère de l’accès standard, en ce qu’elle vous fournit uniquement un accès et non à tous les utilisateurs et utilisatrices.

Vous avez besoin des éléments suivants :

Commandes SSH pour accéder aux environnements. Vous pouvez obtenir ces informations par le biais du Cloud Console ou de votre Cloud Onboarding UI.
La valeur xdebug_key définie lors de la configuration des environnements d’évaluation et Pro.

Vous pouvez trouver le xdebug_key en utilisant SSH pour vous connecter au nœud principal et en exécutant :
cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1

Pour configurer un tunnel SSH vers un environnement d’évaluation ou de production :

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

NOTE

Pour obtenir la valeur correcte de USERNAME@CLUSTER.ent.magento.cloud :

Méthode 1 : interface de ligne de commande magento-cloud : magento-cloud ssh --all
Méthode 2 : console Commerce : https://CONSOLE-URL/ENVIRONMENT, cliquez sur la liste déroulante SSH v .

Pour commencer le débogage à l’aide de l’URL d’environnement :

Il s’agit d’une démonstration des configurations utilisées, ainsi que du paramètre de GET permettant de démarrer une session de débogage à distance.

video poster

https://video.tv.adobe.com/v/3437417?learn=on

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
NOTE
Les XDEBUG_SESSION_START transmises par POST requêtes ne sont pas prises en charge.

Commandes de débogage de l’interface de ligne de commande

Cette section décrit les commandes de l’interface de ligne de commande de débogage.

Pour déboguer les commandes de l’interface de ligne de commande :

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

Déboguer les requêtes web

Les étapes suivantes vous aident à déboguer les requêtes web.

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.

Exemple : configuration de Chrome

Cette section explique comment utiliser Xdebug dans Chrome à l’aide de l’extension Xdebug Helper. Pour plus d’informations sur les outils de Xdebug pour d’autres navigateurs, consultez la documentation du navigateur.

Pour utiliser Xdebug Helper avec Chrome :

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.

Déboguer le code local

En raison des environnements en lecture seule, vous devez extraire du code vers le poste de travail local à partir d’un environnement ou d’une branche Git spécifique pour effectuer le débogage.

La méthode que vous choisissez dépend de vous. Les options disponibles sont les suivantes :

Extraire le code à partir de Git et exécuter composer install

Cette méthode fonctionne, sauf si composer.json fait référence à des packages dans des référentiels privés auxquels vous n’avez pas accès. Cette méthode permet d’obtenir la base de code Adobe Commerce complète.
Copiez les répertoires vendor, app, pub, lib et setup

Grâce à cette méthode, vous disposez de tout le code que vous pouvez tester. Selon le nombre de ressources statiques dont vous disposez, un long transfert peut être nécessaire avec un grand volume de fichiers.
Copiez uniquement le répertoire vendor

Comme la plupart du code se trouve dans le répertoire vendor, cette méthode est susceptible d’entraîner de bons tests, bien que ne testent pas l’ensemble de la base de code.

Pour compresser des fichiers et les copier sur votre ordinateur local :

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

recommendation-more-help