DocumentazioneCommerceGuida di Commerce su infrastruttura Cloud

Configura Xdebug

Last update: Fri Jul 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Creato per:

  • Amministratore
  • Sviluppatore

Xdebug è un'estensione per il debug del tuo PHP. Sebbene sia possibile utilizzare un IDE scelto, di seguito viene illustrato come configurare Xdebug e PhpStorm per il debug nell'ambiente locale.

NOTE
È possibile configurare Xdebug per l'esecuzione nell'ambiente Cloud Docker per il debug locale senza modificare la configurazione del progetto Adobe Commerce su infrastruttura cloud. Vedere Configurare Xdebug per Docker.

Per abilitare Xdebug, devi configurare un file nell'archivio Git, configurare l'IDE e configurare l'inoltro delle porte. È possibile configurare alcune impostazioni nel file magento.app.yaml. Dopo la modifica, invia le modifiche Git in tutti gli ambienti Starter e gli ambienti di integrazione Pro per abilitare Xdebug. Xdebug è già disponibile negli ambienti Pro Staging & Production.

Una volta configurata, è possibile eseguire il debug di comandi CLI, richieste Web e codice. Ricorda che tutti gli ambienti dell’infrastruttura cloud sono di sola lettura. Clona il codice nell’ambiente di sviluppo locale per eseguire il debug. Per gli ambienti di staging e produzione Pro, consulta ulteriori istruzioni per Xdebug.

Requisiti

Per eseguire e utilizzare Xdebug, è necessario l'URL SSH per l'ambiente. È possibile individuare le informazioni tramite Cloud Console o Cloud Onboarding UI.

Configura Xdebug

Per configurare Xdebug, eseguire la procedura seguente:

Introduzione a un ramo

Per aggiungere Xdebug, l'Adobe consiglia di lavorare in un ramo di sviluppo.

Abilitare Xdebug nell’ambiente

È possibile abilitare Xdebug direttamente in tutti gli ambienti Starter e gli ambienti di integrazione Pro. Questo passaggio di configurazione non è necessario per gli ambienti di produzione e staging Pro. Consulta Debug per Pro Staging e Produzione.

Per abilitare Xdebug per il progetto, aggiungere xdebug alla sezione runtime:extensions del file .magento.app.yaml.

Per abilitare Xdebug:

  1. Nel terminale locale, apri il file .magento.app.yaml in un editor di testo.

  2. Nella sezione runtime, in extensions, aggiungi xdebug. Ad esempio:

    code language-yaml 
    runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug

  3. Salvare le modifiche apportate al file .magento.app.yaml e uscire dall'editor di testo.

  4. Aggiungi, esegui il commit e invia le modifiche per ridistribuire l’ambiente.

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

Quando viene implementato in ambienti Starter e Pro Integration, Xdebug è ora disponibile. Continua a configurare l’IDE. Per PhpStorm, vedere Configurare PhpStorm.

Configurare PhpStorm

L'IDE PhpStorm deve essere configurato per funzionare correttamente con Xdebug.

Per configurare PhpStorm per l'utilizzo con Xdebug:

  1. Nel progetto PhpStorm, apri il pannello Impostazioni.

    • macOS—Seleziona PhpStorm > Preferenze.
    • Windows/Linux—Selezionare File > Impostazioni.

  2. Nel pannello Impostazioni, espandi e individua la sezione Lingue e framework > PHP > Server.

  3. Fare clic su + per aggiungere una configurazione del server. Il nome del progetto è in grigio nella parte superiore.

  4. [Facoltativo] Configura le impostazioni seguenti per la nuova configurazione del server. Consulta Nessun server di debug configurato nella documentazione di PHPStorm.

    • Nome - Immettere lo stesso nome host. Questo valore deve corrispondere al valore per la variabile PHP_IDE_CONFIG in Debug dei comandi CLI per utilizzare CLI per il debug.
    • Host - Immettere il nome host.
    • Porta - Immettere 443.
    • Debugger—Selezionare Xdebug.

  5. Seleziona Usa mappature percorso. Nel riquadro File/Directory viene visualizzata la directory principale del progetto per serverName.

  6. Nella colonna Percorso assoluto sul server fare clic sull'icona Modifica e aggiungere un'impostazione basata sull'ambiente.

    • Per tutti gli ambienti Starter e di integrazione Pro, il percorso remoto è /app.

    • Per ambienti di staging e produzione Pro:

      • Produzione: /app/<project_code>/
      • Gestione temporanea: /app/<project_code>_stg/

  7. Modificare la porta Xdebug in 9000 nel pannello Language & Frameworks > PHP > Debug > Xdebug > Debug Port.

  8. Fare clic su Applica.

Configurare l’inoltro delle porte

Mappa la connessione XDEBUG dal server al sistema locale. Per eseguire qualsiasi tipo di debug, è necessario inoltrare la porta 9000 dal server Adobe Commerce su infrastruttura cloud al computer locale. Vedere una delle sezioni seguenti:

Inoltro porte in Mac o UNIX®

Per impostare l'inoltro delle porte in un ambiente Mac o UNIX®:

  1. Apri un terminale.

  2. Utilizza SSH per stabilire la connessione.

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

    Utilizzare l'opzione -v (dettagliata) in modo che ogni volta che un socket è connesso alla porta che viene inoltrata venga visualizzato nel terminale.

    Se viene visualizzato l'errore "Impossibile connettersi" o "Impossibile ascoltare la porta in remoto", potrebbe essere presente un'altra sessione SSH attiva persistente sul server che occupa la porta 9000. Se la connessione non viene utilizzata, è possibile terminarla.

Per risolvere i problemi di connessione:

  1. Utilizza SSH per accedere all’integrazione remota, all’ambiente di staging o di produzione.

  2. Visualizza elenco sessioni SSH: who

  3. Visualizzare le sessioni SSH esistenti per utente. Fai attenzione a non avere effetti su utenti diversi da te!

    • integrazione: i nomi utente sono simili a dd2q5ct7mhgus
    • Staging: i nomi utente sono simili a dd2q5ct7mhgus_stg
    • Produzione: i nomi utente sono simili a dd2q5ct7mhgus

  4. Per una sessione utente precedente alla tua, trova il valore dello pseudo-terminale (PTS), ad esempio pts/0.

  5. Termina il PID (Process ID) corrispondente al valore PTS.

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

    Risposta di esempio:

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

    Per terminare la connessione, immettere un comando kill con l'ID processo (PID).

    code language-bash 
    kill 3664

Inoltro porte in Windows

Per impostare l'inoltro delle porte (tunneling SSH) su Windows, è necessario configurare l'applicazione terminale Windows. In questo esempio viene eseguita la creazione di un tunnel SSH utilizzando Putty. È possibile utilizzare altre applicazioni, ad esempio Cygwin. Per ulteriori informazioni su altre applicazioni, consulta la documentazione del fornitore fornita con tali applicazioni.

Per configurare un tunnel SSH in Windows utilizzando Putty:

  1. Se non lo hai già fatto, scarica Putty.

  2. Avvia Putty.

  3. Nel riquadro Categoria fare clic su Sessione.

  4. Immettere le seguenti informazioni:

    • Campo Nome host (o indirizzo IP): immetti l'URL SSH per il server cloud
    • Campo Porta: immetti 22

    Configurazione di Putty

  5. Nel riquadro Categoria fare clic su Connessione > SSH > Tunnel.

  6. Immettere le seguenti informazioni:

    • Campo Porta Source: immetti 9000
    • Campo Destinazione: immetti 127.0.0.1:9000
    • Fai clic su Remoto

  7. Fare clic su Aggiungi.

    Crea un tunnel SSH in Putty

  8. Nel riquadro Categoria fare clic su Sessione.

  9. Nel campo Sessioni salvate immettere un nome per il tunnel SSH.

  10. Fai clic su Salva.

    Salva il tunnel SSH

  11. Per verificare il tunnel SSH, fai clic su Carica, quindi su Apri.

    Se viene visualizzato un errore di tipo "Impossibile connettersi", verificare quanto segue:

    • Tutte le impostazioni di Putty sono corrette
    • Stai eseguendo Putty sul computer in cui si trovano le chiavi SSH dell’infrastruttura cloud del tuo Adobe Commerce privato

Accesso SSH agli ambienti Xdebug

Per avviare il debug, eseguire l’installazione e altro ancora, sono necessari i comandi SSH per accedere agli ambienti. È possibile ottenere queste informazioni tramite Cloud Console e il foglio di calcolo del progetto.

Per gli ambienti Starter e gli ambienti di integrazione Pro, è possibile utilizzare il seguente comando CLI magento-cloud per SSH in tali ambienti:

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

Per utilizzare Xdebug, SSH nell'ambiente come segue:

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

Ad esempio:

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

Debug per staging e produzione Pro

NOTE
Negli ambienti Pro Staging & Production, Xdebug è sempre disponibile in quanto tali ambienti dispongono di una configurazione speciale per Xdebug. Tutte le normali richieste Web vengono indirizzate a un processo PHP dedicato che non ha Xdebug. Pertanto, queste richieste vengono elaborate normalmente e non sono soggette al deterioramento delle prestazioni quando viene caricato Xdebug. Quando viene inviata una richiesta Web con la chiave Xdebug, questa viene indirizzata a un processo PHP separato in cui è caricato Xdebug.

Per utilizzare Xdebug in modo specifico nell'ambiente di staging e produzione del piano Pro, è necessario creare un tunnel SSH separato e una sessione Web a cui accedere. Questo utilizzo differisce dall’accesso tipico, che fornisce accesso solo a te e non a tutti gli utenti.

Sono necessari i seguenti elementi:

  • Comandi SSH per accedere agli ambienti. Puoi ottenere queste informazioni tramite Cloud Console o il tuo Cloud Onboarding UI.

  • Il valore xdebug_key impostato durante la configurazione degli ambienti Staging e Pro.

    È possibile trovare xdebug_key utilizzando SSH per accedere al nodo primario ed eseguire:

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

Per impostare un tunnel SSH in un ambiente di gestione temporanea o di produzione:

  1. Apri un terminale.

  2. Pulizia di tutte le sessioni SSH per ogni nodo Web del cluster.

    code language-bash 
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'

  3. Impostare il tunnel SSH per Xdebug per ogni nodo Web del cluster.

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

Per avviare il debug utilizzando l'URL dell'ambiente:

  1. Abilitare il debug remoto; visitare il sito nel browser e aggiungere quanto segue all'URL in cui KEY è il valore per xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_START=KEY

    Questo passaggio imposta il cookie che invia le richieste del browser per attivare Xdebug.

  2. Completa il debug con Xdebug.

  3. Quando si è pronti per terminare la sessione, utilizzare il comando seguente per rimuovere il cookie e terminare il debug tramite il browser, dove KEY è il valore di xdebug_key.

    code language-http 
    ?XDEBUG_SESSION_STOP=KEY
    note note
    NOTE
    I XDEBUG_SESSION_START passati da POST richieste non sono supportati.

Debug dei comandi CLI

Questa sezione descrive come eseguire il debug dei comandi CLI.

Per eseguire il debug dei comandi CLI:

  1. SSH nel server di cui eseguire il debug utilizzando i comandi CLI.

  2. Crea le seguenti variabili di ambiente:

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

    Queste variabili vengono rimosse al termine della sessione SSH.

  3. Inizio debug

    Negli ambienti Starter e negli ambienti di integrazione Pro, eseguire il comando CLI per eseguire il debug.
    È possibile aggiungere opzioni di runtime, ad esempio:

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

    Negli ambienti di staging e produzione Pro, è necessario specificare il percorso del file di configurazione PHP Xdebug durante il debug dei comandi CLI, ad esempio:

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

Debug richieste web

I passaggi seguenti sono utili per eseguire il debug delle richieste web.

  1. Nel menu Estensione, fai clic su Debug per abilitare.

  2. Fare clic con il pulsante destro del mouse, selezionare il menu delle opzioni e impostare il tasto IDE su PHPSTORM.

  3. Installa il client Xdebug nel browser. Configuralo e attivalo.

Esempio: configurazione di Chrome

In questa sezione viene descritto come utilizzare Xdebug in Chrome utilizzando l'estensione helper Xdebug. Per informazioni sugli strumenti Xdebug per altri browser, consultare la documentazione del browser.

Per utilizzare Xdebug Helper con Chrome:

  1. Crea un tunnel SSH nel server cloud.

  2. Installa l'estensione Xdebug Helper dall'archivio Chrome.

  3. Abilita l’estensione in Chrome come illustrato nella figura seguente.

    Abilitare lestensione Xdebug in Chrome

  4. In Chrome, fai clic con il pulsante destro del mouse sull’icona verde helper nella barra degli strumenti di Chrome.

  5. Dal menu a comparsa, fare clic su Opzioni.

  6. Nell'elenco Chiave IDE fare clic su PhpStorm.

  7. Fai clic su Salva.

    Opzioni Helper Xdebug

  8. Apri il progetto PhpStorm.

  9. Nella barra di navigazione superiore, fai clic sull'icona Avvia ascolto.

    Se la barra di spostamento non è visualizzata, fare clic su Visualizza > Barra di spostamento.

  10. Nel pannello di navigazione PhpStorm, fate doppio clic sul file PHP da testare.

Debug del codice locale

A causa degli ambienti di sola lettura, per eseguire il debug è necessario richiamare il codice nella workstation locale da un ambiente o da un ramo Git specifico.

Il metodo che scegli dipende da te. Sono disponibili le seguenti opzioni:

  • Estrai il codice da Git ed esegui composer install

    Questo metodo funziona a meno che composer.json non faccia riferimento a pacchetti in archivi privati a cui non hai accesso. Questo metodo consente di ottenere l’intera base di codice di Adobe Commerce.

  • Copia le directory vendor, app, pub, lib e setup

    Questo metodo ti permette di avere tutto il codice che puoi eventualmente testare. A seconda del numero di risorse statiche disponibili, il trasferimento potrebbe richiedere molto tempo, con un volume elevato di file.

  • Copia solo la directory vendor

    Poiché la maggior parte del codice si trova nella directory vendor, è probabile che questo metodo dia luogo a test validi, anche se non stanno testando l'intera base di codice.

Per comprimere i file e copiarli nel computer locale:

  1. Utilizza SSH per accedere all’ambiente remoto.

  2. Comprimi i file.

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

    Ad esempio, per comprimere solo la directory vendor:

    code language-bash 
    tar -czf /tmp/vendor.tgz vendor

  3. Nell'ambiente locale, usare PhpStorm per comprimere i file.

    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