Configuration de Xdebug

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

NOTE
Vous pouvez configurer Xdebug s’exécuter dans l’environnement Cloud Docker pour le débogage local sans modifier la configuration de projet d’infrastructure cloud d’Adobe Commerce. Voir Configuration de Xdebug pour Docker.

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

Une fois la configuration effectuée, vous pouvez déboguer des commandes d’interface de ligne de commande, des requêtes Web et du code. N’oubliez pas que tous les environnements d’infrastructure de cloud sont en lecture seule. Cloner le code vers votre environnement de développement local pour effectuer le débogage. Pour les environnements d’évaluation et de production Pro, voir instructions supplémentaires pour Xdebug.

Conditions

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

Configuration de Xdebug

Pour configurer Xdebug, procédez comme suit :

Prise en main d’une branche

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

Activation de Xdebug dans votre environnement

Vous pouvez activer Xdebug directement à tous les environnements Starter 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.

Pour activer Xdebug pour votre projet, ajoutez xdebug à la fonction runtime:extensions de la .magento.app.yaml fichier .

Pour activer Xdebug:

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

  2. Dans le runtime sous extensions, ajoutez xdebug. Par exemple :

    code language-yaml
    runtime:
        extensions:
            - redis
            - xsl
            - newrelic
            - sodium
            - xdebug
    
  3. Enregistrez vos modifications dans le .magento.app.yaml et quittez l’éditeur de texte.

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

    code language-bash
    git add -A
    
    code language-bash
    git commit -m "Add xdebug"
    
    code language-bash
    git push origin <environment-ID>
    

Lorsqu’ils sont déployés 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 de PhpStorm

La variable PhpStorm IDE doit être configuré pour fonctionner correctement avec Xdebug.

Pour configurer PhpStorm de sorte qu’il fonctionne avec Xdebug:

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

    • macOS—Select PhpStorm > Préférences.
    • Windows/Linux—Select Fichier > Paramètres.
  2. Dans le Paramètres , développez et localisez le panneau Langues et structures > PHP > Serveurs .

  3. Cliquez sur le bouton + pour ajouter une configuration de serveur. Le nom du projet est en gris dans la partie supérieure.

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

    • 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 Commandes de l’interface de ligne de commande de débogage pour utiliser l’interface de ligne de commande pour le débogage.
    • Hôte: saisissez le nom d’hôte.
    • Port—Enter 443.
    • Debugger—Select Xdebug.
  5. Sélectionner Utilisation des mappages de chemins. Dans le Fichier/Répertoire , à la racine du projet pour la serverName s’affiche.

  6. Dans le Chemin absolu sur le serveur , cliquez sur le bouton Modifier et ajoutez un paramètre basé sur l’environnement.

    • Pour tous les environnements Starter 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/
  7. Modifiez la variable Xdebug au port 9000 dans la variable Langues et structures > PHP > Déboguer > Xdebug > Debug Port du panneau.

  8. Cliquez sur Appliquer.

Configuration du transfert de port

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

Transfert de port sur Mac ou UNIX®

Pour configurer le transfert de port dans un environnement Mac ou UNIX®:

  1. Ouvrez un terminal.

  2. Utilisez SSH pour établir la connexion.

    code language-bash
    ssh -R 9000:localhost:9000 <ssh url>
    

    Utilisez la variable -v (verbose) de sorte que chaque fois qu’un socket est connecté au port qui est transféré, il s’affiche dans le terminal.

    Si une erreur "impossible de se connecter" ou "impossible d’écouter le port à distance" 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:

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

  2. Afficher la liste des sessions SSH : who

  3. Affichage des sessions SSH existantes par utilisateur. Veillez à ne pas affecter un utilisateur autre que vous !

    • 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
  4. Pour une session utilisateur plus ancienne que la vôtre, recherchez la valeur pseudo-terminal (PTS), telle que pts/0.

  5. Exécutez l’ID de processus (PID) correspondant à la valeur PTS.

    code language-bash
    ps aux | grep ssh
    kill <PID>
    

    Exemple de réponse :

    code language-terminal
    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 de suppression avec l’ID de processus (PID).

    code language-bash
    kill 3664
    

Transfert de port sous Windows

Pour configurer le transfert de port (tunnel SSH) sous Windows, vous devez configurer votre application de terminal Windows. Cet exemple passe en revue la création d’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 du fournisseur fournie avec ces applications.

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

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

  2. Démarrez Putty.

  3. Dans le volet Catégorie , cliquez sur Session.

  4. Renseignez les informations suivantes :

    • Nom d’hôte (ou adresse IP) champ : saisissez la valeur URL SSH pour votre serveur Cloud
    • Port champ : Entrée 22

    Configuration de Putty

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

  6. Renseignez les informations suivantes :

    • Port source champ : Entrée 9000
    • Destination champ : Entrée 127.0.0.1:9000
    • Cliquez sur Distant
  7. Cliquez sur Ajouter.

    Création d’un tunnel SSH dans Putty

  8. Dans le Catégorie volet, cliquez sur Session.

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

  10. Cliquez sur Enregistrer.

    Enregistrement de votre tunnel SSH

  11. Pour tester le tunnel SSH, cliquez sur Chargement, puis cliquez sur Ouvrir.

    Si une erreur "impossible de se connecter" s’affiche, vérifiez les éléments suivants :

    • Tous les paramètres de coupure sont corrects
    • Vous exécutez Putty sur l’ordinateur sur lequel se trouvent vos clés SSH de votre Adobe Commerce privée 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 à l’aide de la variable 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 les éléments suivants : magento-cloud Commande d’interface de ligne de commande pour SSH dans ces environnements :

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

Pour utiliser Xdebug, SSH à 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 Pro

NOTE
Dans les environnements d’évaluation et de production Pro, Xdebug est toujours disponible, car ces environnements disposent d’une configuration spéciale pour 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 sont pas soumises à une dégradation des performances lorsque Xdebug est chargé. Lorsqu’une requête web est envoyée, qui contient la variable Xdebug clé, elle est acheminée vers un processus PHP distinct qui possède Xdebug chargé.

Pour utiliser Xdebug plus précisément, dans l’environnement d’évaluation et de production Pro, vous créez un tunnel SSH distinct et une session web à laquelle vous avez accès. Cette utilisation diffère de l’accès type, en ce qu’elle ne vous permet d’accéder qu’à vous et non à tous les utilisateurs.

Vous avez besoin des éléments suivants :

  • Commandes SSH pour accéder aux environnements. Vous pouvez obtenir ces informations à l’aide de la variable Cloud Console ou votre Cloud Onboarding UI.

  • La variable xdebug_key valeur définie lors de la configuration des environnements d’évaluation et Pro.

    La variable xdebug_key peut être trouvé en utilisant SSH pour se connecter au noeud principal et s’exécuter :

    code language-bash
    cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1
    

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

  1. Ouvrez un terminal.

  2. Nettoyez toutes les sessions SSH pour chaque noeud web de la grappe.

    code language-bash
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'
    
  3. Configurez le tunnel SSH pour Xdebug pour chaque noeud web de la grappe.

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

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

  1. Activez le débogage à distance. Rendez-vous sur le site dans le navigateur et ajoutez le code suivant à l’URL où KEY est la valeur de xdebug_key.

    code language-http
    ?XDEBUG_SESSION_START=KEY
    

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

  2. Effectuez votre débogage avec Xdebug.

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

    code language-http
    ?XDEBUG_SESSION_STOP=KEY
    
    note note
    NOTE
    La variable XDEBUG_SESSION_START transmis par POST Les requêtes ne sont pas prises en charge.

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

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

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

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

  2. Créez les variables d’environnement suivantes :

    code language-bash
    export XDEBUG_CONFIG='PHPSTORM'
    
    code language-bash
    export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"
    

    Ces variables sont supprimées lorsque la session SSH se termine.

  3. Commencer le débogage

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

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

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

    code language-bash
    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.

  1. Sur le Extension , cliquez sur Déboguer pour l’activer.

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

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

Exemple : configuration de Chrome

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

Pour utiliser Xdebug Helper avec Chrome:

  1. Créez un tunnel SSH sur le serveur Cloud.

  2. Installez le Extension Xdebug Helper à partir de la boutique Chrome.

  3. Activez l’extension dans Chrome, comme illustré dans la figure suivante.

    Activation de l’extension Xdebug dans Chrome

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

  5. Dans le menu contextuel, cliquez sur Options.

  6. Dans la Clé IDE liste, cliquez sur PhpStorm.

  7. Cliquez sur Enregistrer.

    Options de l’assistant Xdebug

  8. Ouvrez votre projet PhpStorm.

  9. Dans la barre de navigation supérieure, cliquez sur le Commencer à écouter Icône

    Si la barre de navigation ne s’affiche pas, cliquez sur Affichage > Barre de navigation.

  10. Dans le volet de navigation de 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. Vous disposez des options suivantes :

  • Extraction de code à partir de Git et exécution composer install

    Cette méthode fonctionne sauf si composer.json référence des modules dans des référentiels privés auxquels vous n’avez pas accès. Cette méthode permet d’obtenir le code base Adobe Commerce entier.

  • Copiez le vendor, app, pub, lib, et setup répertoires

    Avec cette méthode, vous disposez de tout le code que vous pouvez tester. Selon le nombre de ressources statiques dont vous disposez, le transfert avec un volume de fichiers important peut être long.

  • Copiez le vendor directory only

    La plupart du code se trouve dans la variable vendor , cette méthode est susceptible de générer des tests pertinents, même si elle ne teste pas l’ensemble du code base.

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

  1. Utilisez SSH pour vous connecter à l’environnement distant.

  2. Compressez les fichiers.

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

    Par exemple, pour compresser la variable vendor répertoire uniquement :

    code language-bash
    tar -czf /tmp/vendor.tgz vendor
    
  3. Dans votre environnement local, utilisez PhpStorm pour compresser les fichiers.

    code language-bash
    cd <phpstorm project root dir>
    
    code language-bash
    rsync <SSH-URL>:/tmp/<file-name>.tgz .
    
    code language-bash
    tar xzf <file-name>.tgz
    
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26