Xdebug para depurar código PHP remoto

O Xdebug permite percorrer código PHP com pontos de interrupção e examinar as variáveis de um pedido a partir de um IDE compatível.

Utilize-o de preferência em local ou em staging. Uma sessão passo a passo pode expor ao IDE valores de variáveis, credenciais, tokens e dados pessoais processados pelo pedido. Se excecionalmente tiver de o usar em produção, limite o teste a um pedido autorizado, utilize um acionador privado e desative imediatamente a extensão no fim.

O Xdebug pode introduzir uma sobrecarga apreciável conforme o modo ativado e desativa o JIT do PHP enquanto está carregado. Verifique a sua versão real; não a deduza apenas a partir da versão de PHP.

Verificar a disponibilidade e ativar o Xdebug 3

Aceda a cPanel > Select PHP Version para a versão que executa o caminho. Este guia só é aplicável se o seletor oferecer a extensão xdebug e, em Options, a opção xdebug.mode. Ative a extensão e defina xdebug.mode como debug. Esta opção aplica-se ao arrancar o PHP e não pode ser definida a partir de .htaccess nem de .user.ini.

Se alguma destas opções não aparecer, não presuma que o Xdebug está disponível para essa versão. Não tente instalar nem carregar outra extensão dentro da conta.

Se o controlador PHP do domínio admitir diretivas Xdebug em .htaccess, adicione temporariamente:

php_value xdebug.start_with_request trigger
php_flag xdebug.start_upon_error Off
php_flag xdebug.discover_client_host Off
php_value xdebug.client_host 127.0.0.1
php_value xdebug.client_port 9003
php_value xdebug.trigger_value VALOR_ALEATORIO_LARGO

Substitua VALOR_ALEATORIO_LARGO por um valor privado. Estas opções fixam o início por acionador, desativam o início automático por erros e evitam descobrir o destino a partir de cabeçalhos. Verifique os seus valores efetivos: um código que chame xdebug_break() também pode iniciar uma ligação. O acionador privado controla o teste habitual, mas não é um mecanismo de autenticação do protocolo. Se as diretivas provocarem um erro 500, retire-as e verifique o registo: o código, por si só, não demonstra que o controlador as rejeite.

Criar um túnel SSH inverso

O Xdebug inicia a ligação para o IDE; o IDE não se liga ao Xdebug. Nesta configuração, o Xdebug liga-se a 127.0.0.1:9003 no servidor e o túnel SSH reencaminha essa ligação para 127.0.0.1:9003 no seu computador, onde o IDE está à escuta.

Ative previamente o acesso SSH e configure uma chave seguindo o guia de acesso SSH.

Em Linux ou macOS, execute:

ssh -N -p 93 \
  -o ExitOnForwardFailure=yes \
  -R 127.0.0.1:9003:127.0.0.1:9003 \
  USUARIO_CPANEL@TU_DOMINIO.COM

-R abre a porta 9003 apenas na interface de loopback do servidor e reencaminha-a para a porta 9003 do seu computador. Mantenha a sessão aberta só durante o teste. Se o SSH não conseguir criar o reencaminhamento, terminará com erro; não exponha em vez disso a porta do depurador à Internet.

Em Windows, configure o PuTTY com o domínio e a porta 93, usando a chave SSH autorizada no cPanel. Em Connection | SSH | Tunnels, crie um reencaminhamento Remote de 127.0.0.1:9003 para o destino 127.0.0.1:9003. Não ative opções que permitam escutar noutras interfaces do servidor. Se a sessão rejeitar o reencaminhamento remoto, esta via não está disponível para a conta.

Configurar o IDE e reproduzir o pedido

Abra no IDE a mesma versão do código que está implementada e configure o mapeamento entre o caminho remoto e o projeto local. Configure a porta Xdebug 9003, ative a escuta de ligações e adicione os pontos de interrupção.

No PhpStorm, utilize Run > Start Listening for PHP Debug Connections. No NetBeans, configure a porta 9003 e o mapeamento de caminhos remotos. Não é obrigatório sincronizar o projeto por FTP para receber uma sessão de depuração.

Ative o acionador com uma extensão de navegador compatível configurada com o mesmo valor privado, ou adicione XDEBUG_TRIGGER=VALOR_ALEATORIO_LARGO apenas ao pedido de teste. Reproduza a operação necessária uma única vez. Aceder ao URL sem o acionador não deve iniciar a sessão.

No fim, desative o acionador, feche o túnel SSH, elimine as diretivas temporárias, altere xdebug.mode para off ou desative a extensão e verifique que não fica nenhum registo do Xdebug com dados da sessão.

Se precisar de analisar o desempenho em vez de percorrer o código, utilize o PHP X-Ray.

Limites do túnel e verificação

O loopback evita escutar numa interface pública, mas não garante isolamento entre todos os utilizadores de um servidor partilhado. Confirme com o fornecedor que o reencaminhamento é permitido e isolado para o seu ambiente. Se a porta estiver ocupada, combine outra porta remota e ajuste xdebug.client_port; não altere os dados de outro utilizador.

Verifique primeiro que um pedido sem acionador não inicia a sessão e depois que o pedido de teste chega ao ponto de interrupção correto. Não publique um URL com o acionador: pode ficar em históricos ou registos. Elimine também o cookie de depuração no fim. Consulte as opções de depuração do Xdebug se a sessão se iniciar de forma inesperada.