📝 Guia Definitivo: Laravel + Docker + Xdebug no WSL2

Este artigo detalha como configurar um ambiente de desenvolvimento onde o código reside no sistema de arquivos do Linux (WSL), rodando em containers Docker, com debug funcional no VS Code.

1. Por que rodar no diretório do WSL? Link para o cabeçalho

Para performance máxima. O Docker Desktop no Windows tem um gargalo de IO quando acessa arquivos no /mnt/c/. Ao mover o projeto para \\wsl.localhost\Ubuntu\home\..., a aplicação Laravel pode rodar até 10x mais rápido.

2. Configuração do Docker (Dockerfile / PHP) Link para o cabeçalho

No seu container PHP (ex: PHP 7.4), o Xdebug precisa estar instalado e configurado para “discar” para o host correto.

No seu xdebug.ini (dentro do container):

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
xdebug.log=/tmp/xdebug.log

Dica: Se o host.docker.internal falhar no CLI, você pode descobrir o IP do WSL usando hostname -I no terminal do Ubuntu e usá-lo temporariamente.

3. Configuração do VS Code (launch.json) Link para o cabeçalho

O pulo do gato está aqui. Quando você abre o VS Code no modo WSL: Ubuntu, ele age como se estivesse dentro do Linux.

Crie ou edite o arquivo .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "hostname": "0.0.0.0",
            "pathMappings": {
                "/app/sgp": "${workspaceFolder}/backend"
            }
        }
    ]
}

Pontos de Atenção:

• hostname: 0.0.0.0: Essencial! Obriga o VS Code a ouvir conexões de qualquer interface de rede, permitindo que o tráfego do container chegue ao debugger.

• pathMappings: O lado esquerdo é o caminho dentro do container (/app/suaaplicacao). O lado direito é o caminho no WSL (${workspaceFolder}/backend).

4. Como executar e debugar Link para o cabeçalho

Para Requisições Web:

1. No VS Code, vá na aba “Run and Debug” (Ctrl+Shift+D).

2. Selecione “Listen for Xdebug” e dê Play (F5).

3. Coloque um breakpoint no seu Controller.

4. Acesse a URL no navegador.

Para Testes Unitários (PHPUnit) via Terminal:

Se você estiver dentro do container via docker exec, rode o teste injetando o host do WSL para garantir a conexão:

php -dxdebug.client_host=172.xx.xx.xx ./vendor/bin/phpunit --filter NomeDoTeste

(Substitua o IP pelo retornado por hostname -I no seu WSL).

6. Automatizando a Rede no Docker Compose Link para o cabeçalho

Para evitar ter que buscar o IP do WSL (hostname -I) manualmente toda vez que trocar de rede ou reiniciar o PC, adicione a diretiva extra_hosts ao seu serviço PHP. Isso faz com que o container reconheça o host do Windows/WSL automaticamente.

Exemplo de docker-compose.yml:

services:
  php74:
    build: 
      context: .
      dockerfile: Dockerfile
    container_name: php74
    volumes:
      - ./backend:/app/sgp
    # O Pulo do Gato:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - sgp-network

networks:
  sgp-network:
    driver: bridge

Por que isso é importante? O host-gateway é uma palavra-chave especial do Docker que resolve para o endereço IP da interface de rede do host. Com isso, sua configuração no xdebug.ini (xdebug.client_host=host.docker.internal) funcionará de forma nativa e estável.

Diagrama de Fluxo de Conexão Link para o cabeçalho

Para visualizar como o dado trafega desde o seu código até o VS Code:

1. Container: O PHP executa o código e o Xdebug dispara um pacote para host.docker.internal:9003.

2. WSL2: O Docker redireciona esse pacote para o IP do gateway do WSL.

3. VS Code: Como definimos hostname: 0.0.0.0, o VS Code “escuta” essa batida na porta 9003 e intercepta a execução, ativando o seu breakpoint.

Resumo das Configurações de Sucesso Link para o cabeçalho

6. Troubleshooting (Resumo da Solução) Link para o cabeçalho

• Time-out? Verifique se o hostname no launch.json está como 0.0.0.0.

• Não para no breakpoint? Confira se o pathMappings aponta exatamente para a pasta onde está o arquivo artisan.

• Erro de conexão? O Firewall do Windows pode estar bloqueando a porta 9003. Tente criar uma regra de entrada para essa porta.

Com esse setup, seu ambiente Laravel no WSL fica profissional, rápido e, acima de tudo, fácil de debugar!