Configurar Xdebug
Xdebug é uma extensão para depurar seu PHP. Embora você possa usar um IDE de sua escolha, o seguinte explica como configurar o Xdebug e o PhpStorm para depurar em seu ambiente local.
Para habilitar Xdebug, você deve configurar um arquivo no repositório Git, configurar o IDE e configurar o encaminhamento de portas. Você pode definir algumas configurações no arquivo magento.app.yaml
. Após a edição, envie as alterações do Git por push em todos os ambientes de Iniciação e integração Pro para habilitar o Xdebug. O Xdebug já está disponível em ambientes de Preparo e Produção Profissionais.
Depois de configurado, você pode depurar comandos CLI, solicitações da Web e código. Lembre-se de que todos os ambientes de infraestrutura em nuvem são somente leitura. Clonar o código no ambiente de desenvolvimento local para executar a depuração. Para ambientes de Produção e Preparo Pro, consulte instruções adicionais para Xdebug.
Requisitos
Para executar e usar o Xdebug, você precisa da URL SSH do ambiente. Você pode localizar as informações por meio do Cloud Console ou do seu Cloud Onboarding UI.
Configurar Xdebug
Para configurar o Xdebug, siga estas etapas:
Introdução a uma ramificação
Para adicionar Xdebug, o Adobe recomenda trabalhar em uma ramificação de desenvolvimento.
Ativar o Xdebug no seu ambiente
Você pode habilitar o Xdebug diretamente para todos os ambientes de inicialização e integração Pro. Essa etapa de configuração não é necessária para ambientes de produção e preparo profissionais. Consulte Depuração para Preparo e Produção Profissionais.
Para habilitar Xdebug para o seu projeto, adicione xdebug
à seção runtime:extensions
do arquivo .magento.app.yaml
.
Para habilitar Xdebug:
-
No terminal local, abra o arquivo
.magento.app.yaml
em um editor de texto. -
Na seção
runtime
, emextensions
, adicionexdebug
. Por exemplo:code language-yaml runtime: extensions: - redis - xsl - newrelic - sodium - xdebug
-
Salve as alterações no arquivo
.magento.app.yaml
e saia do editor de texto. -
Adicione, confirme e envie as alterações para reimplantar o ambiente.
code language-bash git add -A
code language-bash git commit -m "Add xdebug"
code language-bash git push origin <environment-ID>
Quando implantado em ambientes iniciais e ambientes de integração Pro, o Xdebug agora está disponível. Continue configurando seu IDE. Para PhpStorm, consulte Configurar PhpStorm.
Configurar o PhpStorm
O IDE PhpStorm deve ser configurado para funcionar corretamente com Xdebug.
Para configurar o PhpStorm para funcionar com o Xdebug:
-
No projeto PhpStorm, abra o painel Configurações.
- macOS—Selecione PhpStorm > Preferências.
- Windows/Linux—Selecione Arquivo > Configurações.
-
No painel Configurações, expanda e localize a seção Idiomas e Estruturas > PHP > Servidores.
-
Clique em + para adicionar uma configuração de servidor. O nome do projeto está em cinza na parte superior.
-
[Opcional] Defina as seguintes configurações para a nova configuração do servidor. Consulte Nenhum servidor de depuração configurado na documentação do PHPStorm.
- Nome — Insira o mesmo que o nome de host. Este valor deve corresponder ao valor da variável
PHP_IDE_CONFIG
em Comandos CLI de Depuração para usar a CLI para depuração. - Host — Digite o nome do host.
- Porta — Digite
443
. - Depurador—Selecione
Xdebug
.
- Nome — Insira o mesmo que o nome de host. Este valor deve corresponder ao valor da variável
-
Selecione Usar mapeamentos de caminho. No painel Arquivo/Diretório, a raiz do projeto para
serverName
é exibida. -
Na coluna Caminho absoluto no servidor, clique no ícone Editar e adicione uma configuração com base no ambiente.
-
Para todos os ambientes Starter e Pro integration, o caminho remoto é
/app
. -
Para ambientes de preparo e produção profissionais:
- Produção:
/app/<project_code>/
- Estágios:
/app/<project_code>_stg/
- Produção:
-
-
Altere a porta Xdebug para 9000 no painel Languages & Frameworks > PHP > Debug > Xdebug > Debug Port.
-
Clique em Aplicar.
Configurar encaminhamento de porta
Mapeie a conexão XDEBUG
do servidor para o sistema local. Para fazer qualquer tipo de depuração, você deve encaminhar a porta 9000 do Adobe Commerce no servidor de infraestrutura em nuvem para o computador local. Consulte uma das seguintes seções:
Encaminhamento de portas no Mac ou UNIX®
Para configurar o encaminhamento de portas em um ambiente Mac ou UNIX®:
-
Abra um terminal.
-
Use SSH para estabelecer a conexão.
code language-bash ssh -R 9000:localhost:9000 <ssh url>
Use a opção
-v
(detalhada) para que sempre que um soquete for conectado à porta que está sendo encaminhada ele seja exibido no terminal.Se um erro "não é possível conectar" ou "não foi possível escutar a porta no remoto" for exibido, pode haver outra sessão SSH ativa persistindo no servidor que está ocupando a porta 9000. Se essa conexão não estiver sendo usada, você poderá encerrá-la.
Para solucionar problemas de conexão:
-
Use o SSH para fazer logon no ambiente de integração remota, preparo ou produção.
-
Exibir uma lista de sessões SSH:
who
-
Visualizar sessões SSH existentes por usuário. Tenha cuidado para não afetar um usuário que não seja você mesmo!
- integração: usuários com nomes semelhantes a
dd2q5ct7mhgus
- Estágios: os nomes de usuários são semelhantes a
dd2q5ct7mhgus_stg
- Produção: nomes de usuários semelhantes a
dd2q5ct7mhgus
- integração: usuários com nomes semelhantes a
-
Para uma sessão de usuário mais antiga que a sua, localize o valor do pseudo-terminal (PTS), como
pts/0
. -
Elimine a ID de processo (PID) correspondente ao valor PTS.
code language-bash ps aux | grep ssh kill <PID>
Exemplo de resposta:
code language-none dd2q5ct7mhgus 5504 0.0 0.0 82612 3664 ? S 18:45 0:00 sshd: dd2q5ct7mhgus@pts/0
Para encerrar a conexão, digite um comando kill com o ID do processo (PID).
code language-bash kill 3664
Encaminhamento de porta no Windows
Para configurar o encaminhamento de portas (encapsulamento SSH) no Windows, você deve configurar o aplicativo de terminal do Windows. Este exemplo passa pela criação de um túnel SSH usando Putty. Você pode usar outros aplicativos, como o Cygwin. Para obter mais informações sobre outros aplicativos, consulte a documentação do fornecedor fornecida com esses aplicativos.
Para configurar um túnel SSH no Windows usando Putty:
-
Se ainda não tiver feito isso, baixe Putty.
-
Comece o Putty.
-
No painel Categoria, clique em Sessão.
-
Insira as seguintes informações:
- Campo Nome do host (ou endereço IP): insira a URL do SSH para o seu servidor na nuvem
- Campo Porta: Digite
22
-
No painel Categoria, clique em Conexão > SSH > Túneis.
-
Insira as seguintes informações:
- Campo Porta do Source: Digite
9000
- Campo Destino: Digite
127.0.0.1:9000
- Clique em Remoto
- Campo Porta do Source: Digite
-
Clique em Adicionar.
-
No painel Categoria, clique em Sessão.
-
No campo Sessões Salvas, digite um nome para esse túnel SSH.
-
Clique em Salvar.
-
Para testar o túnel SSH, clique em Carregar e em Abrir.
Se um erro "não é possível conectar" for exibido, verifique o seguinte:
- Todas as configurações de Putty estão corretas
- Você está executando o Putty na máquina em que suas chaves SSH privadas do Adobe Commerce na infraestrutura em nuvem estão localizadas
Acesso SSH a ambientes Xdebug
Para iniciar a depuração, executar a configuração e muito mais, você precisa dos comandos SSH para acessar os ambientes. Você pode obter essas informações por meio do Cloud Console e da planilha do seu projeto.
Para ambientes Starter e ambientes de integração Pro, você pode usar o seguinte comando da CLI magento-cloud
para SSH nesses ambientes:
magento-cloud environment:ssh --pipe -e <environment-ID>
Para usar Xdebug, SSH conecta o ambiente da seguinte maneira:
ssh -R <xdebug listen port>:<host>:<xdebug listen port> <SSH-URL>
Por exemplo,
ssh -R 9000:localhost:9000 pwga8A0bhuk7o-mybranch@ssh.us.magentosite.cloud
Depuração para preparo e produção profissionais
Para usar Xdebug especificamente no ambiente de preparo e produção do plano Pro, você cria um túnel SSH separado e uma sessão da Web somente para os quais tem acesso. Esse uso difere do acesso típico, fornecendo acesso apenas a você e não a todos os usuários.
Você precisa do seguinte:
-
Comandos SSH para acessar os ambientes. Você pode obter essas informações por meio do Cloud Console ou do seu Cloud Onboarding UI.
-
O valor
xdebug_key
definido ao configurar os ambientes de Preparo e Pro.O
xdebug_key
pode ser encontrado usando SSH para fazer logon no nó primário e executando:code language-bash cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1
Para configurar um túnel SSH para um ambiente de Preparo ou de Produção:
-
Abra um terminal.
-
Limpe todas as sessões SSH para cada nó da Web do cluster.
code language-bash ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'
-
Configure o túnel SSH para o Xdebug para cada nó da Web do cluster.
code language-bash ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud
Para iniciar a depuração usando a URL de ambiente:
-
Habilitar depuração remota; visite o site no navegador e anexe o seguinte à URL em que
KEY
é o valor dexdebug_key
.code language-http ?XDEBUG_SESSION_START=KEY
Esta etapa define o cookie que envia solicitações do navegador para o disparador Xdebug.
-
Conclua sua depuração com Xdebug.
-
Quando estiver pronto para encerrar a sessão, use o seguinte comando para remover o cookie e finalizar a depuração pelo navegador, onde
KEY
é o valor dexdebug_key
.code language-http ?XDEBUG_SESSION_STOP=KEY
note note NOTE Não há suporte para o XDEBUG_SESSION_START
passado porPOST
solicitações.
Comandos CLI de depuração
Esta seção aborda os comandos CLI de depuração.
Para depurar comandos da CLI:
-
SSH no servidor que você deseja depurar usando comandos CLI.
-
Crie as seguintes variáveis de 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>"
Essas variáveis são removidas quando a sessão SSH termina.
-
Iniciar depuração
Em ambientes Starter e de integração Pro, execute o comando da CLI para depurar.
Você pode adicionar opções de tempo de execução, por exemplo:code language-bash php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean
Em ambientes de preparo e produção Pro, você deve especificar o caminho para o arquivo de configuração PHP Xdebug ao depurar comandos CLI, por exemplo:
code language-bash php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean
Depurar solicitações da Web
As etapas a seguir ajudam a depurar solicitações da Web.
-
No menu Extensão, clique em Depurar para habilitar.
-
Clique com o botão direito do mouse, selecione o menu de opções e defina a chave IDE como PHPSTORM.
-
Instale o cliente Xdebug no navegador. Configure e ative-o.
Exemplo: configuração do Chrome
Esta seção discute como usar o Xdebug no Chrome usando a extensão Auxiliar do Xdebug. Para obter informações sobre as ferramentas do Xdebug para outros navegadores, consulte a documentação do navegador.
Para usar o Auxiliar Xdebug com o Chrome:
-
Crie um túnel SSH para o servidor na nuvem.
-
Instale a Extensão auxiliar do Xdebug do armazenamento do Chrome.
-
Ative a extensão no Chrome como mostrado na figura a seguir.
-
No Chrome, clique com o botão direito do mouse no ícone verde auxiliar na barra de ferramentas do Chrome.
-
No menu suspenso, clique em Opções.
-
Na lista Chave IDE, clique em PhpStorm.
-
Clique em Salvar.
-
Abra o projeto PhpStorm.
-
Na barra de navegação superior, clique no ícone Iniciar escuta.
Se a barra de navegação não for exibida, clique em Exibir > Barra de Navegação.
-
No painel de navegação do PhpStorm, clique duas vezes no arquivo PHP para testar.
Depurar código local
Devido aos ambientes somente leitura, você deve extrair código para a estação de trabalho local de um ambiente ou ramificação Git específica para executar a depuração.
O método que você escolher depende de você. Você tem as seguintes opções:
-
Confira o código do Git e execute
composer install
Este método funciona a menos que
composer.json
faça referência a pacotes em repositórios privados aos quais você não tem acesso. Este método resulta na obtenção de toda a base de código do Adobe Commerce. -
Copiar os diretórios
vendor
,app
,pub
,lib
esetup
Esse método resulta em ter todos os códigos que você pode testar. Dependendo de quantos ativos estáticos você tem, isso pode resultar em uma longa transferência com um grande volume de arquivos.
-
Copiar somente o diretório
vendor
Como a maioria do código está no diretório
vendor
, esse método provavelmente resultará em um bom teste, embora não esteja testando toda a base de código.
Para compactar arquivos e copiá-los no computador local:
-
Use o SSH para fazer logon no ambiente remoto.
-
Compacte os arquivos.
code language-bash tar -czf /tmp/<file-name>.tgz <directory list>
Por exemplo, para compactar somente o diretório
vendor
:code language-bash tar -czf /tmp/vendor.tgz vendor
-
Em seu ambiente local, use o PhpStorm para compactar os arquivos.
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