Configura Xdebug
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.
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:
-
Nel terminale locale, apri il file
.magento.app.yaml
in un editor di testo. -
Nella sezione
runtime
, inextensions
, aggiungixdebug
. Ad esempio:code language-yaml runtime: extensions: - redis - xsl - newrelic - sodium - xdebug
-
Salvare le modifiche apportate al file
.magento.app.yaml
e uscire dall'editor di testo. -
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:
-
Nel progetto PhpStorm, apri il pannello Impostazioni.
- macOS—Seleziona PhpStorm > Preferenze.
- Windows/Linux—Selezionare File > Impostazioni.
-
Nel pannello Impostazioni, espandi e individua la sezione Lingue e framework > PHP > Server.
-
Fare clic su + per aggiungere una configurazione del server. Il nome del progetto è in grigio nella parte superiore.
-
[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
.
- Nome - Immettere lo stesso nome host. Questo valore deve corrispondere al valore per la variabile
-
Seleziona Usa mappature percorso. Nel riquadro File/Directory viene visualizzata la directory principale del progetto per
serverName
. -
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/
- Produzione:
-
-
Modificare la porta Xdebug in 9000 nel pannello Language & Frameworks > PHP > Debug > Xdebug > Debug Port.
-
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®:
-
Apri un terminale.
-
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:
-
Utilizza SSH per accedere all’integrazione remota, all’ambiente di staging o di produzione.
-
Visualizza elenco sessioni SSH:
who
-
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
- integrazione: i nomi utente sono simili a
-
Per una sessione utente precedente alla tua, trova il valore dello pseudo-terminale (PTS), ad esempio
pts/0
. -
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:
-
Se non lo hai già fatto, scarica Putty.
-
Avvia Putty.
-
Nel riquadro Categoria fare clic su Sessione.
-
Immettere le seguenti informazioni:
- Campo Nome host (o indirizzo IP): immetti l'URL SSH per il server cloud
- Campo Porta: immetti
22
-
Nel riquadro Categoria fare clic su Connessione > SSH > Tunnel.
-
Immettere le seguenti informazioni:
- Campo Porta Source: immetti
9000
- Campo Destinazione: immetti
127.0.0.1:9000
- Fai clic su Remoto
- Campo Porta Source: immetti
-
Fare clic su Aggiungi.
-
Nel riquadro Categoria fare clic su Sessione.
-
Nel campo Sessioni salvate immettere un nome per il tunnel SSH.
-
Fai clic su Salva.
-
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
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:
-
Apri un terminale.
-
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'
-
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:
-
Abilitare il debug remoto; visitare il sito nel browser e aggiungere quanto segue all'URL in cui
KEY
è il valore perxdebug_key
.code language-http ?XDEBUG_SESSION_START=KEY
Questo passaggio imposta il cookie che invia le richieste del browser per attivare Xdebug.
-
Completa il debug con Xdebug.
-
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 dixdebug_key
.code language-http ?XDEBUG_SESSION_STOP=KEY
note note NOTE I XDEBUG_SESSION_START
passati daPOST
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:
-
SSH nel server di cui eseguire il debug utilizzando i comandi CLI.
-
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.
-
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.
-
Nel menu Estensione, fai clic su Debug per abilitare.
-
Fare clic con il pulsante destro del mouse, selezionare il menu delle opzioni e impostare il tasto IDE su PHPSTORM.
-
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:
-
Crea un tunnel SSH nel server cloud.
-
Installa l'estensione Xdebug Helper dall'archivio Chrome.
-
Abilita l’estensione in Chrome come illustrato nella figura seguente.
-
In Chrome, fai clic con il pulsante destro del mouse sull’icona verde helper nella barra degli strumenti di Chrome.
-
Dal menu a comparsa, fare clic su Opzioni.
-
Nell'elenco Chiave IDE fare clic su PhpStorm.
-
Fai clic su Salva.
-
Apri il progetto PhpStorm.
-
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.
-
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
esetup
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:
-
Utilizza SSH per accedere all’ambiente remoto.
-
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
-
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