Bora configurar o Xdebug

Nunca vi um tutorial simples ensinando a configurar o Xdebug com Docker e Direnv. Neste mini tutorial, vou tentar dar o meu máximo para esclarecer e ensiná-los. Lembrando que este não é um tutorial para explicar o que é o Xdebug ou como utilizá-lo, mas sim para instalá-lo. Para isso, você pode ler a documentação ou assistir a este vídeo do YouTube.

Nesse tutorial utilizo:

• PHP 7.3
• Docker
• Zsh
• Direnv

Primeiro, vamos configurar o direnv.

Instalação:

    sudo apt install direnv
   

Para configurar o terminal, adicione a linha abaixo ao arquivo .zshrc. Assim, sempre que você acessar uma pasta contendo um arquivo .envrc, o Direnv será ativado automaticamente.

    eval "$(direnv hook zsh)"
   

Agora, vamos criar o arquivo .envrc com o seguinte conteúdo na raiz do seu projeto:

    #!/usr/bin/env bash

    export DOCKER_HOST_IP=$(hostname -I | awk '{print $1}')
   

Na primeira vez que você acessar a pasta pelo terminal, será necessário executar o comando abaixo para permitir que o Direnv leia o arquivo .envrc

    direnv allow
   

No seu arquivo Dockerfile, é necessário habilitar o Xdebug, lembrando que o Xdebug é um módulo do PHP, então ele fica dentro do seu php.ini

    # Instalar e habilitar extensões PECL e Xdebug
    RUN pecl install  -o -f xdebug-3.1.5 \
    && docker-php-ext-enable  xdebug
   

Ainda no Dockerfile, precisamos configurar o php.ini. Não vamos entrar manualmente no container para alterá-lo.

    COPY ./docker/php.ini /usr/local/etc/php/conf.d/php-custom.ini
   

Na raiz do seu projeto, crie uma pasta chamada docker e dentro dela um arquivo php.ini, Adicione a seguinte linha ao arquivo:

    xdebug.mode = develop,debug
   

Neste exemplo, estou usando o PHP 7.3, o que implica que o Xdebug está na versão 3.1.5. Para verificar as versões compatíveis com o PHP, acesse este link.

No docker-compose.yml, adicione um bloco environment dentro do serviço do seu container que contenha o PHP.

    
    environment:
    - XDEBUG_CONFIG=client_host=${DOCKER_HOST_IP:-}
    

Essa configuração define o endereço IP do cliente para o Xdebug no ambiente Docker. Nesse caso, o cliente é a sua máquina de desenvolvimento.

Configurando a extensão do VsCode:

Instale a extensão que permitirá a depuração do código: PHP Debug

Após a instalação, abra o arquivo launch.json, apague todo o conteúdo e deixe apenas o seguinte script:

    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Listen for Xdebug",
                "type": "php",
                "request": "launch",
                "port": 9003,
                "pathMappings": {
                    "/var/www/html": "${pathMappings}"
                }
            }
        ]
    }
   

Para rodar começar a utilizar o Xdebug, coloque o breakpoint no local que deseja que o código pare, de preferencia para testar, coloque ele em um arquivo de conexão com o banco de dados, só para teste, deps rretire e coloque aonde desejar. Agora basta apertar no play locazilado em algum lugar do seu vscode com a opção “Listen For Debug¨ ou ctrl + shift + p, e pesquise por Debug (PHP) Start Listening for Xdebug.

Agora vamos inicializar na web, em sua URL basta passar o seguinte parametro:

    ?XDEBUG_SESSION_START=true
   

vai ficar algo como: http://127.0.0.1/dashboard?XDEBUG_SESSION_START=true

Após iniciar a sessão, não precisa mais passar esse parametro até que a sessão seja encerrada.