Configura Xdebug

Xdebug è un’estensione per il debug del PHP. Sebbene sia possibile utilizzare un IDE a scelta, di seguito viene illustrato come configurare Xdebug e PhpStorm per eseguire il debug nell’ambiente locale.

NOTE
Puoi configurare Xdebug per l’esecuzione nell’ambiente Cloud Docker per il debug locale senza modificare la configurazione del progetto Adobe Commerce on cloud infrastructure. Consulta Configurare Xdebug per Docker.

Per abilitare Xdebug, è necessario configurare un file nell’archivio Git, configurare l’IDE e impostare l’inoltro delle porte. È possibile configurare alcune impostazioni in magento.app.yaml file. Dopo l'editing, implementare le modifiche Git in tutti gli ambienti Starter e 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 istruzioni aggiuntive 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, effettua le seguenti operazioni:

Introduzione a un ramo

Da aggiungere Xdebug, Adobe consiglia di lavorare in un ramo di sviluppo.

Abilitare Xdebug nell’ambiente

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

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

Per abilitare Xdebug:

  1. Nel terminale locale, aprire .magento.app.yaml in un editor di testo.

  2. In runtime sezione, sotto extensions, aggiungi xdebug. Ad esempio:

    code language-yaml
    runtime:
        extensions:
            - redis
            - xsl
            - newrelic
            - sodium
            - xdebug
    
  3. Salva le modifiche in .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>
    

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

Configurare PhpStorm

Il PhpStorm L’IDE deve essere configurato in modo da funzionare correttamente con Xdebug.

Per configurare PhpStorm per l'utilizzo con Xdebug:

  1. Nel progetto PhpStorm, aprite Impostazioni pannello.

    • macOS- Seleziona PhpStorm > Preferenze.
    • Windows/Linux- Seleziona File > Impostazioni.
  2. In Impostazioni , espandere e individuare il Lingue e framework > PHP > Server sezione.

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

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

    • Nome- Immetti lo stesso nome host. Questo valore deve corrispondere al valore per PHP_IDE_CONFIG variabile in Debug dei comandi CLI per utilizzare CLI per il debug.
    • Host- Immettere il nome host.
    • Porta- Invio 443.
    • Debugger- Seleziona Xdebug.
  5. Seleziona Utilizzare le mappature dei percorsi. In File/Directory , la directory principale del progetto per serverName visualizzazioni.

  6. In Percorso assoluto sul server , fare clic sul pulsante Modifica e aggiungere un'impostazione basata sull'ambiente.

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

    • Per ambienti di staging e produzione Pro:

      • Produzione: /app/<project_code>/
      • Staging: /app/<project_code>_stg/
  7. Modificare il Xdebug porta a 9000 nel Lingue e framework > PHP > Debug > Xdebug > Porta di debug pannello.

  8. Clic Applica.

Configurare l’inoltro delle porte

Mappa il XDEBUG connessione 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>
    

    Utilizza il -v (verbose) 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 un elenco di 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-terminal
    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 descritto come creare 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 impostare un tunnel SSH su 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:

    • Nome host (o indirizzo IP) campo: immettere il URL SSH per il server cloud
    • Porta campo: Invio 22

    Configurazione di Putty

  5. In Categoria , fare clic su Connessione > SSH > Tunnel.

  6. Immettere le seguenti informazioni:

    • Porta di origine campo: Invio 9000
    • Destinazione campo: Invio 127.0.0.1:9000
    • Clic Remoto
  7. Clic Aggiungi.

    Creare un tunnel SSH in Putty

  8. In Categoria , fare clic su Sessione.

  9. In Sessioni salvate immettere un nome per il tunnel SSH.

  10. Clic Salva.

    Salvare il tunnel SSH

  11. Per verificare il tunnel SSH, fare clic su Carica, quindi fai clic 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. Puoi 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 quanto segue magento-cloud Comando CLI per SSH in questi ambienti:

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

Da utilizzare Xdebug, SSH per l’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 di staging e produzione Pro, Xdebug è sempre disponibile in quanto questi ambienti dispongono di una configurazione 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 Xdebug è caricato. Quando viene inviata una richiesta web con Xdebug principale, viene indirizzato a un processo PHP separato che ha Xdebug caricato.

Da utilizzare Xdebug in particolare nell'ambiente Pro plan Staging and Production, è possibile creare un tunnel SSH separato e una sessione web solo a cui si ha accesso. 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 Cloud Onboarding UI.

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

    Il xdebug_key può essere trovato utilizzando SSH per accedere al nodo principale ed eseguire:

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

Per impostare un tunnel SSH in un ambiente di staging o 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. Abilita il debug remoto; visita il sito nel browser e aggiungi quanto segue all’URL, dove KEY è il valore di xdebug_key.

    code language-http
    ?XDEBUG_SESSION_START=KEY
    

    Questo passaggio imposta il cookie che invia le richieste del browser per l'attivazione Xdebug.

  2. Completa il debug con Xdebug.

  3. Quando sei pronto per terminare la sessione, utilizza il seguente comando per rimuovere il cookie e terminare il debug tramite il browser in cui KEY è il valore di xdebug_key.

    code language-http
    ?XDEBUG_SESSION_STOP=KEY
    
    note note
    NOTE
    Il XDEBUG_SESSION_START passato da POST richieste non supportate.

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 Xdebug File di configurazione PHP 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. Il giorno Estensione menu, fai clic su Debug per attivare.

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

  3. Installare Xdebug sul browser. Configuralo e attivalo.

Esempio: configurazione di Chrome

Questa sezione illustra come utilizzare Xdebug in Chrome utilizzando Xdebug Estensione helper. Per informazioni su Xdebug strumenti per altri browser, consulta la documentazione del browser.

Per utilizzare Xdebug Helper con Chrome:

  1. Creare un Tunnel SSH al server cloud.

  2. Installare Estensione Xdebug Helper dal negozio Chrome.

  3. Abilitate l'estensione in Chrome come mostrato nella figura seguente.

    Abilitare l’estensione 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. Dalla sezione Chiave IDE , fare clic su PhpStorm.

  7. Clic Salva.

    Opzioni Helper Xdebug

  8. Apri il progetto PhpStorm.

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

    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 fa 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 il vendor, app, pub, lib, e setup directory

    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 il vendor solo directory

    Perché la maggior parte del codice si trova in vendor , questo metodo produrrà probabilmente risultati di 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 vendor solo directory:

    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