DEV Community

Cover image for Xdebug 3, Docker, Laravel, VScode
Jhonatan Morais
Jhonatan Morais

Posted on • Edited on

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
Enter fullscreen mode Exit fullscreen mode

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 ...]
Enter fullscreen mode Exit fullscreen mode

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:

Config gráfica do xdebug

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.

Exemplo para configuraçao da extensão de debug

Configuração no VSCode.

Extensão de debug do vscode

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
        }
    ]
}

Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

preview do debug em uso

Referências

Top comments (9)

Collapse
 
goodnato profile image
Renato Alves

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

Collapse
 
getjv profile image
Jhonatan Morais

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.

Collapse
 
goodnato profile image
Renato Alves
Collapse
 
zobo profile image
Damjan Cvetko

Great article, although I', not exactly sure why the hostname would be required - since by default it should listen on 0.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...

Collapse
 
getjv profile image
Jhonatan Morais

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.

Collapse
 
devatreides profile image
Tom Benevides

Eu li muita coisa mas o seu artigo tá demais amigo, funcionou perfeitamente \o/

Collapse
 
getjv profile image
Jhonatan Morais

Que satisfação esse comentário. Fico feliz que ajudou.
esse xdebug é chato de configurar mas não da pra codar sem ele. hahaha

Collapse
 
devatreides profile image
Tom Benevides

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 ( :

Collapse
 
richellyitalo profile image
Richelly Italo

Excelente Jhonatan.
Muito obrigado!