Xdebug: entenda como funciona e como resolver problemas na sua configuração
Desenvolvimento, Magento 2
Atualizado em 02 de agosto de 2023
Xdebug é uma extensão PHP. Ela permite que aplicações desta linguagem se conectem a uma IDE, permitindo pausar e depurar a mesma em tempo de execução.
Apesar de ser uma ferramenta quase indispensável na vida do desenvolvedor moderno, quase ninguém usa. 🤯
A desculpa é sempre a mesma: “nunca consigo configurar”. Tanto para usuários do PhpStorm como aqueles que usam Visual Studio Code (VsCode).
Neste artigo vamos entender melhor como ele funciona. Também vamos ver como configurar e como resolver problemas comuns da sua configuração.
Para os fins deste artigo, usaremos o XDebug 3.
Acesso rápido
Como o Xdebug funciona
Esteja você usando o PHP no Docker, WSL, ou mesmo na sua própria máquina, é importante que a extensão do XDebug esteja ativada.
Somente assim ele poderá funcionar junto com seus arquivos PHP em tempo de execução.
Uma vez que ele é executado e está ativo, ele se conectará à máquina especificada em xdebug.client_host no seu PHP.
Como saber se o Xdebug está ativo
Para saber confirmar se a extensão está ativa no php, basta digitar php -v.
Com isso podemos ver não apenas a versão do PHP mas também se o Xdebug foi iniciado.
No entanto, sua extensão pode estar carregada, mas pode não estar ativada.
Configurações do Xdebug. Onde e como mudar.
Uma vez que a extensão está carregada, é preciso realizar configurações adicionais. Você precisará especificar:
- quando o xdebug deverá interceptar a execução do código
- para qual máquina ele deve enviar informações
- em que porta
- entre outras coisas 🙂
Todas estas configurações podem ser definidas no php.ini ou em arquivos de configuração .ini carregados adicionalmente.
Ao digitar php -i | grep -i xdebug você terá uma lista das configurações carregadas por ele.
Veja alguns exemplos:
$ php -i | grep -i xdebug xdebug.auto_trace => (setting renamed in Xdebug 3) => (setting renamed in Xdebug 3) xdebug.cli_color => 0 => 0 xdebug.client_discovery_header => no value => no value xdebug.client_host => host.docker.internal => host.docker.internal xdebug.client_port => 9003 => 9003 xdebug.cloud_id => no value => no value ...
Geralmente um arquivo .ini é carregado separadamente com as configurações do xdebug. Basta alterar este arquivo e reiniciar o servidor web para alterá-las.
Você também pode adicionar/mapear um novo arquivo .ini a um dos diretórios que o PHP busca arquivos de configuração.
Para listar esses diretórios, basta digitar php --ini, como no exemplo abaixo.
Sendo assim, ao adicionar um arquivo .ini a um dos diretórios marcados em verde acima, você pode alterar as configurações e parâmetros do xdebug. Exemplo:
xdebug.mode=debug
Isso iria alterar o valor da configuração do parâmetro xdebug.mode. Para confirmar se a configuração foi aplicada, digite php -i | grep -i xdebug.mode. Lembre-se de reiniciar seu servidor web todas as vezes que alterar uma configuração php.
Xdebug e suas configurações ideais iniciais
Sempre que estou iniciando a configuração do Xdebug em um projeto, faço ela de forma a ter ele sendo executado em todas as requisições. Isto porque podemos configurar o Xdebug para ser iniciado somente no caso da existência de determinado cookie. Mas isso abriria margem para erros na configuração do navegador.
Sendo assim, faço sempre uma safe config antes de otimizar a forma como vou iniciá-lo.
No Xdebug 3, costumo deixar meu .ini acima da seguinte forma:
xdebug.mode=debug xdebug.start_with_request=yes xdebug.discover_client_host=0 xdebug.client_host=host.docker.internal xdebug.port=9003 xdebug.connect_timeout_ms=2000
xdebug.mode=debug xdebug.start_with_request=yes xdebug.discover_client_host=1 xdebug.client_host=localhost xdebug.port=9003 xdebug.connect_timeout_ms=2000
Acima você viu os exemplos de configuração do xdebug com e sem o uso de docker. No segundo caso, o xdebug tentará identificar o ip da máquina do desenvolvedor, e se não conseguir, usará o client_host especificado.
Também costumo aumentar o timeout para 2 segundos nas primeiras execuções e até ter certeza que está tudo funcionando.
Você pode ver uma lista de todas as configurações possíveis neste link.
Configuração do VsCode com Xdebug 3
Para configurar o Xdebug no Visual Studio Code da Microsoft você precisará de uma ou duas extensões adicionais.
O primeiro passo é fazer download da extensão oficial do Xdebug, chamada PHP Debug.
Se você estiver utilizando WSL2, também precisará da extensão WSL da Microsoft.
Depois clique em Run and Debug (Ctrl + Shift + D); Show all automatic debug configurations; Add configuration; e selecione PHP.
Um arquivo .vscode/launch.json será criado em seu projeto. Dentro dele, você verá uma configuração com o nome “Listen for Xdebug”. Certifique-se que a porta configurada é a mesma que configurou acima, no PHP.
Se estiver usando Docker, também precisará configurar o “pathMappings” e “hostname”, como mostrado na imagem abaixo.
O pathMappings deve mapear as pastas que estão no servidor docker (lado esquerdo) com aquelas da sua máquina, em seu projeto atual (lado direito).
Para usuários Windows e WSL
Se estiver usando WSL, também precisará liberar ele no Windows Defender. Para isso, execute o PowerShell como administrador e digite o comando abaixo:
New-NetFirewallRule -DisplayName “WSL” -Direction Inbound -InterfaceAlias “vEthernet (WSL)” -Action Allow
Isso criará uma nova regra chamada “WSL” no seu Windows Defender.
E pronto. Basta adicionar um breakpoint em alguma linha, e iniciar a escuta do Xdebug clicando em Run and Debug (Ctrl + Shift + D) e clicand no Play (Listen for Xdebug…).
No PhpStorm
Para configurar o Xdebug no PhpStorm da Jetbrains é bem mais fácil e nenhuma extensão adicional é necessária. As liberações do firewall são quase automáticas e são solicitadas e configuradas pelo próprio PhpStorm. Basta autorizar quando for pedido.
O primeiro passo é se certificar que a IDE está configurada para escutar a porta configurada no php.ini (como vimos acima).
Isso é feito nas configurações da IDE em PHP > Debug > Debug port.
Opcionalmente marque a opção “Break at first line in PHP Scripts”. Ao menos enquanto configura o xdebug pela primeira vez em seu projeto.
Isso é suficiente para a maioria dos projetos não-docker.
Basta clicar no ícone de debug para começar a escutar conexões, deixando-o verde.
Se estiver usando Docker, precisará mapear uma variável de ambiente PHP_IDE_CONFIG com o nome do servidor configurado no PhpStorm, como mostro nas imagens abaixo.
services:
phpfpm:
volumes: *appvolumes
environment:
PHP_IDE_CONFIG: "serverName=MeuDocker"
Troubleshooting: Como saber se o servidor consegue se conectar ao Xdebug?
É comum que problemas de firewall, rede, ou mesmo da IDE impeçam o sucesso da nossa configuração Xdebug.
Uma forma simples de testar isso é usando o netcat e ping na máquina que está executando nossa aplicação PHP.
Em máquinas linux, ou docker, você talvez precise instalar estas ferramentas. Para isso, digite:
sudo apt update && sudo apt install -y inetutils-ping netcat
Depois, para testar, certifique-se que sua IDE (PhpStorm, VsCode, etc) está escutando e esperando conexões Xdebug.
Por fim, no servidor da aplicação, digite:
# nc -vz host.docker.internal 9003 Connection to host.docker.internal (192.168.65.254) 9003 port [tcp/*] succeeded!
# ping host.docker.internal PING host.docker.internal (192.168.65.254): 56 data bytes 64 bytes from 192.168.65.254: icmp_seq=0 ttl=62 time=1.617 ms 64 bytes from 192.168.65.254: icmp_seq=1 ttl=62 time=1.768 ms
Ambos os comandos devem mostrar alguma forma de sucesso ao se conectar na máquina do desenvolvedor. Se isso não acontecer, é possível que algo esteja errado.
No lugar de host.docker.internal use o host configurado no php.ini, como vimos acima.
Note que, em alguns casos, o comando acima apenas mostrará que a conexão está aberta (open), o que já é suficiente.
Onde obter mais detalhes? E o Debug com Magento?
Você pode assistir a uma live que fiz sobre o assunto no vídeo abaixo.
Se preferir, também temos uma seção completa sobre Docker e Docker no Windows, no Magento 2: O Curso (do Magenteiro.com).
Espero que tenha gostado. Mais que isso, espero nunca mais ver você usando um echo "passou aqui";.
Se puder, compartilhe este artigo com outros desenvolvedores que ainda fazem isso.
Grande abraço e até a próxima.
- PagSeguro (PagBank) para Magento 1 recebe a Nova Geração - 9 de abril de 2024
- Recorrência no WooCommerce Sem Plugins Pagos - 28 de janeiro de 2024
- Chargeback. O que é, e como se livrar deles. - 19 de dezembro de 2023
Deixe seu comentário
[fbcomments url="https://www.magenteiro.com/blog/magento-2/desenvolvimento-m2/xdebug-phpstorm-vscode-como-configurar/"]