Xdebug 3, Docker, Laravel, VScode

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 e docker-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:

1. O modo script/terminal. que não é o foco desse guia.
2. 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.
3. 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:

1. Clique no besouro com o botão direito e va em opções.
2. Selecione a opção others e coloque a chave como VSCODE (que é o mesmo valor que passamos para o xdebug.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

1. Vá em File > preferences > settings
2. Na tela de Settings vá em Features > Debug
3. Habilite a opção Allow setting breakpoints in any file.

Configurando o debug

1. Clique no contexto de debug do VScode (fica no side menu do lado esquerdo)
2. Clique para criar o arquivo launch.json
3. 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