Xdebug 3, Docker, Laravel, VScode
Tags: xdebug, docker, laravel, vscode
Published: 2021-03-23 16:06:55

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](https://hub.docker.com/r/getjv/php-apache) 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](https://xdebug.org/docs/upgrade_guide). 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:

![Config gráfica do xdebug](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y66wzk3prozk96gdxfhv.png)

**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.](https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc) [Para demais navegadores veja na doc oficial](https://xdebug.org/docs/step_debug#browser-extensions)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/b43hq6j2sv5sbt1cz7q9.png)

## Configuração no VSCode.

#### Extensão de debug do vscode

* Instale a [extensão do felix](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug), 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.](https://youtu.be/s-ot-Zh8LRQ) 

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:

![preview do debug em uso](https://media.giphy.com/media/3jEpbvxllrtB4uMlY1/source.gif)


## Referências

* Muitos outros posts do stakoverflow e claro a documentação oficial [xdebug](https://xdebug.org)
* Um agradecimento especial para [laptrinhx.com](https://laptrinhx.com/vscode-dockerkontena-neinophpwodebaggusuru-ji-host-docker-internalni-jie-xudekinai-wen-tino-dui-chu-3354546647/) que me ajudou a resolver o hots:0.0.0.0
* [Foto de George Becker no Pexels utilizada na capa](https://www.pexels.com/pt-br/foto/1-1-3-texto-no-quadro-negro-374918/)