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