Neste guia mostro uma das várias maneiras de configurar seu xdebug em um ambiente PHP com docker.
Configurar o xdebug sempre foi chato! mas não da pra codar sem ele e agora com sua versão 3 (que ficou excelente) e com docker as coisas ficaram bem mais fáceis. Vamos para a ação!
Imagem docker
Tenho uma imagem de estimação que uso pra trabalhar com docker em meu projetos laravel. Então ela e a base de minha configuração.
Instalação do xdebug 3
Depois de várias horas estudando essa foi a melhor configuração que cheguei :
trecho do meu dockerFile
[ ... outros comandos ... ]
RUN yes | pecl install xdebug \
&& docker-php-ext-enable xdebug \
&& echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
&& echo "xdebug.idekey=VSCODE" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
&& echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
&& echo "xdebug.remote_connect_back=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
&& echo "xdebug.log=/var/www/html/xdebug.log" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
&& touch /var/www/html/xdebug.log \
&& chown developer:www-data /var/www/html/xdebug.log \
&& chmod 775 /var/www/html/xdebug.log
Algumas explicações:
-
pecl install xdebug
edocker-php-ext-enable xdebug
Instala e habilita o xdebug 3 na minha imagem. -
xdebug.mode=debug
coloca o modo de debug desejado -
xdebug.idekey=VSCODE
coloca a chave personalizada utilizada no vscode. -
xdebug.client_host=host.docker.internal
define o host para o docker. -
xdebug.log=/var/www/html/storage/logs/xdebug.log
local para o arquivo de log do xdebug. Como estou utilizando laravel o coloquei nessa path pra evitar problemas de escrita.
Apenas esses parametros já instalam e configuram o xdebug no ambiente.
Atenção: Diversos tutoriais e post utilizam parametors das versões 2.x.x do xdebug que foram descontinuados ou que são redundantes. Sempre leia a documentação oficial para entender o objetivo de cada instrução.
Verificando se o xdebug 3 esta instalado
Método 1 - Modo texto
Com o container rodando entre no bash do mesmo e execute php -i | grep xdebug
a saída deve ser algo assim:
jhonatan@desktop:~/git/my_project$ docker exec -it my_container bash
root@e466f2d7bd63:/var/www/html# php -i | grep xdebug
/usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini,
xdebug
Support Xdebug on Patreon, GitHub, or as a business: https://xdebug.org/support
Enabled Features<br/>(through 'xdebug.mode' setting)
[.. várias variáveis aqui ...]
Método 2 - Modo gráfico
Assim como temos o phpinfo()
para ver a configuração do php temos o xdebug_info()
. Basta colocar ele num script e o resultado visual vai aparecer como o exemplo abaixo:
Atenção: Observe a seção Diagnostc log
é nela que serão apresentadas as mensagem de erro e que estarão impedindo seu debug de funcionar. Essa seção é sua melhor amiga e vai te ajudar a identificar seus problemas.
Configuração da extensão do navegador.
Basicamente temos 3 configurações pra debugar:
-
O modo script/terminal
. que não é o foco desse guia. -
O modo 'toda debuga toda request'
que torna seu ambiente lento pois toda e qualquer request vai iniciar usar o modo debug, pra ativa-la se usa o parâmetro:xdebug.start_with_request=yes
. -
O modo com extensão
que só usa o debug SE a extensão estiver ativada (besouro verde) E o modo debug habilidato no vscode. É esta que utilizaremos neste guia.
Para instalar a extensão em navegadores baseados em chrominium (chrom e edge) utilize esse link. Para demais navegadores veja na doc oficial
Para ativar a extensão:
- Clique no besouro com o botão direito e va em opções.
- Selecione a opção
others
e coloque a chave como VSCODE (que é o mesmo valor que passamos para oxdebug.idekey
la em nosso dockerfile) e salve.
Configuração no VSCode.
Extensão de debug do vscode
- Instale a extensão do felix, ou outra de sua preferência.
Ativando breakpoints
- Vá em
File > preferences > settings
- Na tela de Settings vá em
Features > Debug
- Habilite a opção
Allow setting breakpoints in any file.
Configurando o debug
- Clique no contexto de debug do VScode (fica no side menu do lado esquerdo)
- Clique para criar o arquivo launch.json
- Essa é a minha configuração:
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"hostname": "0.0.0.0",
"port": 9003,
"log": true,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
"ignore": ["**/vendor/**/*.php"],
"xdebugSettings": {
"max_children": 10000,
"max_data": 10000,
"show_hidden": 1
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9000
}
]
}
Atenção: Observe o parametro "hostname": "0.0.0.0",
esse é a config que me salvou. sem ela você vai receber o erro abaixo a todo momento pois o host docker não estará mapeado. exemplo dos recebidos por mapeamento incorreto entre host/docker/vscode:
-
[Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(
ou [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(
Docker-compose e Video demostrativo
Pra facilitar mais e ver tudo em funcionamento adicionei esse video demostrativo e com umas explicações a mais.
Caso vocês queira utilizar a mesma imagem que eu uso aqui esta a docker-compose.yml
version: "3"
services:
backend:
container_name: backend
image: getjv/php-apache
restart: always
ports:
- "80:80"
volumes:
- .:/var/www/html
environment:
- DOCUMENT_ROOT_CONTEXT=public
- ALLOW_OVERRIDE_OPTION=All
- APPLICATION_ENV_OPTION=development
Conclusão e preview de uso.
Pronto! com isso você já deve ter o debug funcionando. Ligue o debug no navegador e no vscode, coloque seus breakpoints e seja feliz.
Espero que estas infos tenham sido úteis. Lembre-se de compartilhar em suas redes certamente vai ajudar muita gente que tem o mesmo problema que você.
Compartilhe sempre o que é bom! e dê crédito aos seus autores.
Segue o preview:
Referências
- Muitos outros posts do stakoverflow e claro a documentação oficial xdebug
- Um agradecimento especial para laptrinhx.com que me ajudou a resolver o hots:0.0.0.0
- Foto de George Becker no Pexels utilizada na capa
Top comments (9)
Oi amigo. Fiz exatamente que voce fez mas meus breakpoints nao funcionam :(
Pelos logs você consegue ver se está tudo certo? Eu nunca consegui fazer o debug funcionar com docker pode me ajudar PF?
Se precisar falar comigo tem meu twitter @goodnato ou meu discord Goodnato#8053
Obrigado
Fala Renato. Antes tarde do que nunca.
cara realmente configurar o xdebug e bem chatinho e acredite antes era bem pior.
Eu atualizei o post com novas infos e tbm coloquei um video mostrando como tudo funciona.
youtube.com/watch?v=s-ot-Zh8LRQ
Caso vc assim como eu esteja usando windows + wsl2, tem ocorrido uns erros de rede interna do docker a atrapalha. Mas geralmente reiniciar a maquina resolve.
Pela imagem que vc mandou, parece ser exatamente isso.
dev-to-uploads.s3.amazonaws.com/up...
Great article, although I', not exactly sure why the
hostname
would be required - since by default it should listen on0.0.0.0
. (nodejs.org/api/net.html#net_server...)I've posted an article regarding the latest release of vscode-php-debug extension: dev.to/zobo/vscode-php-debug-relea...
Hi DamJam I'm Glad you liked. Thank you for the feedback.
That's true, but even the hostname listen 0.0.0.0 I like to 're-force' some crutial default configs params. It's tick from the 2000's hehe.
Eu li muita coisa mas o seu artigo tá demais amigo, funcionou perfeitamente \o/
Que satisfação esse comentário. Fico feliz que ajudou.
esse xdebug é chato de configurar mas não da pra codar sem ele. hahaha
hahah'... correção: "ele era chato de configurar" pq eu fiz rapidinho seguindo seu artigo. Eu tive que mexer só em algumas coisas nos parâmetros do xdebug.ini tipo: "remote_connect_back" mudei pra "discover_client_host", tive que adicionar o "start_with_request=trigger" (que é o equivalente do "remote_mode") mas fora isso foi tudo belezinha... e a doc do XDebug ajuda também, vi tudo aqui:
xdebug.org/docs/upgrade_guide
Eu não conhecia essa ferramenta... um amigo do trabalho que apresentou e cara, ela é demais mesmo ( :
Excelente Jhonatan.
Muito obrigado!