Konfigurera Xdebug

Xdebug är ett tillägg till felsökning av PHP. Även om du kan använda en integrerad utvecklingsmiljö som du väljer beskrivs hur du konfigurerar Xdebug och PhpStorm för felsökning i den lokala miljön.

NOTE
Du kan konfigurera Xdebug så att den körs i Cloud Docker-miljön för lokal felsökning utan att ändra din projektkonfiguration för Adobe Commerce för molninfrastruktur. Se Konfigurera Xdebug för Docker.

Om du vill aktivera Xdebug måste du konfigurera en fil i Git-databasen, konfigurera IDE och konfigurera portvidarebefordran. Du kan konfigurera vissa inställningar i filen magento.app.yaml. Efter redigering kan du aktivera Xdebug genom att överföra Git-ändringarna i alla Starter-miljöer och Pro-integreringsmiljöer. Xdebug är redan tillgängligt i Pro Staging & Production-miljöer.

När konfigurationen är klar kan du felsöka CLI-kommandon, webbförfrågningar och kod. Kom ihåg att alla molninfrastrukturmiljöer är skrivskyddade. Klona koden i den lokala utvecklingsmiljön för att utföra felsökningen. För Pro-miljöer för mellanlagring och produktion, se ytterligare instruktioner för Xdebug.

Krav

Om du vill köra och använda Xdebug behöver du SSH-URL:en för miljön. Du kan hitta informationen via Cloud Console eller Cloud Onboarding UI.

Konfigurera Xdebug

Så här konfigurerar du Xdebug:

Kom igång med en gren

Om du vill lägga till Xdebug rekommenderar Adobe att du arbetar i en utvecklingsgren.

Aktivera Xdebug i miljön

Du kan aktivera Xdebug direkt i alla Starter-miljöer och Pro-integreringsmiljöer. Det här konfigurationssteget krävs inte för Pro Production & Staging-miljöer. Se Felsök för Pro Staging and Production.

Om du vill aktivera Xdebug för ditt projekt lägger du till xdebug i avsnittet runtime:extensions i filen .magento.app.yaml.

Så här aktiverar du Xdebug:

  1. Öppna filen .magento.app.yaml i en textredigerare i din lokala terminal.

  2. Lägg till xdebug under extensions i avsnittet runtime. Exempel:

    code language-yaml
    runtime:
        extensions:
            - redis
            - xsl
            - newrelic
            - sodium
            - xdebug
    
  3. Spara ändringarna i filen .magento.app.yaml och avsluta textredigeraren.

  4. Lägg till, implementera och kör ändringarna för att omdistribuera miljön.

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

Xdebug är nu tillgängligt när den distribueras till Starter-miljöer och Pro-integreringsmiljöer. Fortsätt konfigurera IDE. Information om PhpStorm finns i Konfigurera PhpStorm.

Konfigurera PhpStorm

IDE:n PhpStorm måste vara konfigurerad för att fungera korrekt med Xdebug.

Så här konfigurerar du PhpStorm så att det fungerar med Xdebug:

  1. Öppna panelen Inställningar i ditt PhpStorm-projekt.

    • macOS - Välj PhpStorm > Inställningar.
    • Windows/Linux - Välj Arkiv > Inställningar.
  2. Expandera och leta upp avsnittet Språk och ramar > PHP > Servrar i panelen Inställningar.

  3. Klicka på + för att lägga till en serverkonfiguration. Projektnamnet är grått högst upp.

  4. [Valfritt] Konfigurera följande inställningar för den nya serverkonfigurationen. Se Ingen felsökningsserver har konfigurerats i PHPStorm -dokumentationen.

    • Namn - Ange samma som värdnamn. Det här värdet måste matcha värdet för variabeln PHP_IDE_CONFIG i Felsök CLI-kommandon för att kunna använda CLI för felsökning.
    • Värd - Ange värdnamnet.
    • Port - Ange 443.
    • Felsökning - Välj Xdebug.
  5. Välj Använd banavbildningar. I rutan Fil/katalog visas roten för projektet för serverName.

  6. Klicka på ikonen Redigera i kolumnen Absolut sökväg på servern och lägg till en inställning baserad på miljön.

    • Fjärrsökvägen är /app för alla Starter-miljöer och Pro-integreringsmiljöer.

    • För Pro Staging- och Production-miljöer:

      • Produktion: /app/<project_code>/
      • Mellanlagring: /app/<project_code>_stg/
  7. Ändra porten Xdebug till 9000 i panelen Språk och ramverk > PHP > Felsök > Xdebug > Felsök port.

  8. Klicka på Använd.

Konfigurera portvidarebefordran

Mappa XDEBUG-anslutningen från servern till det lokala systemet. För att kunna utföra alla typer av felsökning måste du vidarebefordra port 9000 från din Adobe Commerce på molninfrastrukturservern till din lokala dator. Se något av följande avsnitt:

Portvidarebefordran på Mac eller UNIX®

Så här konfigurerar du portvidarebefordran på en Mac eller i en UNIX®-miljö:

  1. Öppna en terminal.

  2. Använd SSH för att upprätta anslutningen.

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

    Använd alternativet -v (utförligt) så att när en socket är ansluten till porten som vidarebefordras visas den i terminalen.

    Om ett fel av typen"Det gick inte att ansluta" eller"det gick inte att lyssna på porten på fjärrservern" visas, kan det finnas en annan aktiv SSH-session som är beständig på servern och som upptar port 9000. Om den anslutningen inte används kan du avsluta den.

Så här felsöker du anslutningen:

  1. Använd SSH för att logga in på fjärrintegrerings-, mellanlagrings- eller produktionsmiljön.

  2. Visa en lista över SSH-sessioner: who

  3. Visa befintliga SSH-sessioner per användare. Var noga med att inte påverka andra användare än dig själv!

    • integrering: användarnamn liknar dd2q5ct7mhgus
    • Mellanlagring: användarnamn liknar dd2q5ct7mhgus_stg
    • Produktion: användarnamn liknar dd2q5ct7mhgus
  4. För en användarsession som är äldre än din bör du hitta pseudoterminalvärdet (PTS), till exempel pts/0.

  5. Avsluta process-ID (PID) som motsvarar PTS-värdet.

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

    Exempelsvar:

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

    Om du vill avsluta anslutningen anger du ett avslutskommando med process-ID (PID).

    code language-bash
    kill 3664
    

Portvidarebefordran i Windows

Om du vill konfigurera portvidarebefordran (SSH-tunnling) på Windows måste du konfigurera Windows-terminalprogrammet. I det här exemplet skapas en SSH-tunnel med Putty. Du kan använda andra program som Cygwin. Mer information om andra program finns i leverantörsdokumentationen som medföljer dessa program.

Så här konfigurerar du en SSH-tunnel i Windows med Putty:

  1. Hämta Putty om du inte redan har gjort det.

  2. Starta Putty.

  3. Klicka på Session i kategorirutan.

  4. Ange följande information:

    • Fältet Värdnamn (eller IP-adress): Ange SSH-URL för molnservern
    • Port-fält: Retur 22

    Konfigurera Putty

  5. Klicka på Anslutning > SSH > Tunnlar i rutan Kategori.

  6. Ange följande information:

    • Source-portfält: Ange 9000
    • Målfält: Ange 127.0.0.1:9000
    • Klicka på Fjärr
  7. Klicka på Lägg till.

    Skapa en SSH-tunnel i Putty

  8. Klicka på Session i rutan Kategori.

  9. Ange ett namn för den här SSH-tunneln i fältet Sparade sessioner.

  10. Klicka på Spara.

    Spara SSH-tunneln

  11. Om du vill testa SSH-tunneln klickar du på Läs in och sedan på Öppna.

    Om ett "Det går inte att ansluta"-fel visas kontrollerar du följande:

    • Alla mjuka inställningar är korrekta
    • Du kör Putty på den dator där din privata Adobe Commerce på SSH-nycklar för molninfrastruktur finns

SSH-åtkomst till Xdebug-miljöer

För att starta felsökning, utföra inställningar med mera behöver du SSH-kommandona för att komma åt miljöerna. Du kan hämta den här informationen genom Cloud Console och ditt projektkalkylblad.

I Starter-miljöer och i Pro-integreringsmiljöer kan du använda följande magento-cloud CLI-kommando för SSH i dessa miljöer:

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

Om du vill använda Xdebug, SSH till miljön enligt följande:

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

Exempel:

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

Debug for Pro Staging and Production

NOTE
I Pro Staging & Production-miljöer är Xdebug alltid tillgängligt eftersom dessa miljöer har en särskild konfiguration för Xdebug. Alla normala webbbegäranden dirigeras till en dedikerad PHP-process som inte har Xdebug. Därför behandlas dessa begäranden normalt och påverkas inte av prestandaförsämringen när Xdebug läses in. När en webbförfrågan skickas som har nyckeln Xdebug dirigeras den till en separat PHP-process som har Xdebug inläst.

Om du vill använda Xdebug specifikt i Pro-planens miljö för mellanlagring och produktion skapar du en separat SSH-tunnel och webbsession som du bara har tillgång till. Den här användningen skiljer sig från den vanliga åtkomsten, som bara ger dig åtkomst och inte till alla användare.

Du behöver följande:

  • SSH-kommandon för åtkomst till miljöer. Du kan hämta den här informationen genom Cloud Console eller Cloud Onboarding UI.

  • Värdet xdebug_key som anges när du konfigurerar mellanlagrings- och Pro-miljöerna.

    xdebug_key kan hittas genom att använda SSH för att logga in på den primära noden och köra:

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

Så här konfigurerar du en SSH-tunnel till en mellanlagrings- eller produktionsmiljö:

  1. Öppna en terminal.

  2. Rensa alla SSH-sessioner för varje webbnod i klustret.

    code language-bash
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'
    
  3. Konfigurera SSH-tunneln för Xdebug för varje webbnod i klustret.

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

Så här startar du felsökningen med URL:en för miljön:

  1. Aktivera fjärrfelsökning. Gå till webbplatsen i webbläsaren och lägg till följande till URL:en där KEY är värde för xdebug_key.

    code language-http
    ?XDEBUG_SESSION_START=KEY
    

    I det här steget anges den cookie som skickar webbläsarbegäranden till utlösaren Xdebug.

  2. Slutför felsökningen med Xdebug.

  3. När du är redo att avsluta sessionen använder du följande kommando för att ta bort cookien och avsluta felsökningen via webbläsaren där KEY är värde för xdebug_key.

    code language-http
    ?XDEBUG_SESSION_STOP=KEY
    
    note note
    NOTE
    XDEBUG_SESSION_START som skickades av POST-begäranden stöds inte.

Felsöka CLI-kommandon

I det här avsnittet beskrivs CLI-kommandona för felsökning.

Så här felsöker du CLI-kommandon:

  1. SSH in på den server som du vill felsöka med CLI-kommandon.

  2. Skapa följande miljövariabler:

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

    Dessa variabler tas bort när SSH-sessionen avslutas.

  3. Starta felsökning

    Kör CLI-kommandot för att felsöka i Starter-miljöer och i Pro-integreringsmiljöer.
    Du kan lägga till körningsalternativ, till exempel:

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

    I Pro Staging- och Production-miljöer måste du ange sökvägen till PHP-konfigurationsfilen Xdebug när du felsöker CLI-kommandon, till exempel:

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

Felsöka webbförfrågningar

Följande steg hjälper dig att felsöka webbförfrågningar.

  1. Klicka på Felsök på menyn Tillägg för att aktivera.

  2. Högerklicka, välj alternativmenyn och ställ in IDE-tangenten på PHPSTORM.

  3. Installera klienten Xdebug i webbläsaren. Konfigurera och aktivera den.

Exempel: Chrome-konfiguration

I det här avsnittet beskrivs hur du använder Xdebug i Chrome med hjälp av tillägget Xdebug Helper. Information om Xdebug-verktyg för andra webbläsare finns i webbläsardokumentationen.

Så här använder du Xdebug Helper med Chrome:

  1. Skapa en SSH-tunnel till molnservern.

  2. Installera hjälptillägget för Xdebug från Chrome Store.

  3. Aktivera tillägget i Chrome enligt bilden nedan.

    Aktivera Xdebug-tillägget i Chrome

  4. Högerklicka på den gröna hjälpikonen i Chrome verktygsfält i Chrome.

  5. Klicka på Alternativ på snabbmenyn.

  6. Klicka på PhpStorm i listan IDE-nyckel.

  7. Klicka på Spara.

    Hjälpalternativ för Xdebug

  8. Öppna ditt PhpStorm-projekt.

  9. Klicka på ikonen Börja lyssna i det övre navigeringsfältet.

    Om navigeringsfältet inte visas klickar du på Visa > Navigeringsfält.

  10. Dubbelklicka på den PHP-fil som ska testas i PHpStorm-navigeringsrutan.

Felsöka lokal kod

På grund av skrivskyddade miljöer måste du hämta kod till den lokala arbetsstationen från en miljö eller en specifik Git-gren för att kunna utföra felsökning.

Det är upp till dig att välja metod. Du har följande alternativ:

  • Checka ut kod från Git och kör composer install

    Den här metoden fungerar om inte composer.json refererar till paket i privata databaser som du inte har åtkomst till. Den här metoden leder till att hela Adobe Commerce-kodbasen hämtas.

  • Kopiera katalogerna vendor, app, pub, lib och setup

    Den här metoden gör att du får all kod som du kan testa. Beroende på hur många statiska resurser du har kan det resultera i en lång överföring med en stor mängd filer.

  • Kopiera endast katalogen vendor

    Eftersom större delen av koden finns i katalogen vendor resulterar den här metoden troligen i bra testning, men testar inte hela kodbasen.

Så här komprimerar du filer och kopierar dem till den lokala datorn:

  1. Använd SSH för att logga in i fjärrmiljön.

  2. Komprimera filerna.

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

    Om du till exempel bara vill komprimera katalogen vendor:

    code language-bash
    tar -czf /tmp/vendor.tgz vendor
    
  3. I din lokala miljö använder du PhpStorm för att komprimera filerna.

    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