Configurando o Xdebug no PHPStorm

A depuração é um dos processos mais importantes na programação. Com a ajuda de um depurador, pode ver o que está a acontecer no programa, que funções são executadas, o que está armazenado nas variáveis, bem como executar tudo passo a passo e compreender exatamente em que linha e em que valores das variáveis ocorre um erro.

Por exemplo, o depurador Xdebug é utilizado para PHP e o PHPStorm é um dos ambientes de desenvolvimento mais populares. A seguir, vamos ver como configurar o Xdebug no PhpStorm para depuração no computador local e no Docker.

Configurando o XDEBUG no PHPSTORM

Vamos falar sobre como a depuração é feita no servidor local.

Vamos ver todo o processo usando o Ubuntu e o interpretador PHP configurado com o Apache como exemplo. Para outras configurações, os caminhos dos arquivos podem ser diferentes, mas o ponto é o mesmo. O depurador Xdebug permite pausar a execução do código, ver a pilha de chamadas e o conteúdo das variáveis. A sua única desvantagem é que não existe uma interface de controlo conveniente. Os IDE são normalmente utilizados para gerir a depuração. Mas o IDE não pode dizer ao depurador para iniciar a depuração porque é responsável apenas pelo código. Para este efeito, é necessária a extensão do browser Debug Helper, com a qual pode ativar o modo de depuração.

Primeiro, é necessário instalar o Xdebug. Para o fazer, execute:

$ sudo apt install xdebug

Quando o processo de instalação do Xdebug estiver concluído, deve configurar o programa de modo a que, quando iniciar uma sessão de depuração, tente ligar-se ao nosso IDE para controlar a depuração. Para isso, adicione estas linhas ao ficheiro /etc/php/7.4/apache2/conf.d/20-xdebug.ini na versão Xdebug 2:

$ sudo vi /etc/php/7.4/apache2/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=false

Para uma versão mais recente, é melhor usar um formato diferente:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = 127.0.0.1
xdebug.client_port = 9000

Vamos dar uma olhada mais de perto nas configurações. O primeiro parâmetro xdebug.mode - modo de depuração, as opções possíveis são:

• develop - ativa a saída de informação adicional, substitui o var_dump;

• debug - modo de execução de código linha a linha, é o modo de que precisamos neste caso;

• profile - criação de perfis;

• trace -rastreio da execução do programa.

Vários modos são activados simultaneamente quando listados entre vírgulas. A segunda linha xdebug.start_with_request define como o depurador será iniciado para os modos debug, trace e semelhantes:

• yes - sempre, ao executar scripts php;
• no - iniciar apenas a partir do código usando funções especiais;
• trigger - a pedido, utilizando uma variável especial em $_ENV, $_POST, $COOKIE ou outra matriz. Esta opção adequa-se melhor neste caso, para que o depurador não seja executado quando não é necessário.

A terceira xdebug.discover_client_host é definida como verdadeira, caso em que o xdebug tenta ligar-se ao anfitrião passado no cabeçalho HTTP_X_FORWARDED_FOR. Como o host é especificado na próxima linha, esse recurso não é necessário neste caso. Em seguida, o anfitrião cliente a ligar para o controlo de depuração é 127.0.0.1 e a porta 9000. Essa é a porta padrão usada no PhpStorm no momento. Depois de salvar as configurações, é necessário reiniciar o Apache usando um comando especial:

$ sudo systemctl restart apache2

De seguida, deve configurar o PhpStorm. Execute o programa e abra o menu Run -> Edit Configurations (Executar -> Editar configurações). Aparecerá uma janela onde é necessário configurar o depurador.

Clique no botão + e selecione PHP Remote Debugger na lista que se abre:

Não altere nada nas definições, apenas especifique o nome deste método de depuração. Se não especificar o servidor a partir do qual as ligações serão esperadas, todas as ligações serão aceites.

Se pretender alterar a porta à qual o Xdebug se ligará, abra Ficheiro -> Definições -> PHP -> Depurar -> DBGp Proxy. Aqui pode especificar a porta desejada.

Podemos dizer que agora o IDE está pronto. Agora clique no bug na barra de ferramentas superior. O programa começará a aguardar que o depurador se ligue e colocaremos alguns pontos de interrupção no código, bastando clicar à frente da linha com o código:

Agora só falta configurar o navegador.Para o Chrome, pode descarregar uma extensão especial. Instale-a e abra a página que pretende depurar. Clique no ícone da extensão e selecione Depurar. O ícone da extensão ficará verde:

Actualize a página e volte ao PHPStorm. Se tudo tiver sido feito corretamente, será iniciada uma sessão de depuração. Na primeira execução, o programa pode pedir-lhe que configure os caminhos dos ficheiros locais para corresponderem aos caminhos dos ficheiros remotos. Para o servidor local, não é necessário configurar nada aqui, basta clicar em Aceitar:

Depois disso, o depurador interromperá a execução no ponto de interrupção selecionado e a interface de depuração aparecerá no programa:

Agora vamos entender como configurar o Xdebug PhpStorm e o Docker.

Depurando PHP no DOCKER

O Docker pode ser um pouco complicado. Como o depurador precisa se conectar ao próprio IDE, é necessário encaminhar o host para o contêiner. No Windows, isso pode ser feito usando o endereço host.docker.internal. Mas no Linux, isso não acontece por padrão. Para adicionar esse endereço, é necessário adicionar as seguintes linhas ao docker-compose:

extra_hosts:

host.docker.internal: host-gateway

Usamos a seguinte estrutura de diretórios:

O docker-compose.yaml mínimo necessário terá a seguinte aparência:

version: '3.5'
networks:
  losst-network:
services:
  nginx:
    image: nginx
    ports:
        - '8094:80'
    volumes:
        - ./www/:/var/www/
        - ./conf/nginx:/etc/nginx/conf.d
    networks:
        - losst-network
  php-fpm:
    build: 
      context: ./conf/php-fpm
    extra_hosts:
      host.docker.internal: host-gateway
    volumes:
      - ./www:/var/www/
    networks:
      - losst-network

Nós simplesmente declaramos dois containers, nginx e php-fpm. Não fazemos nenhuma alteração no primeiro, então podemos simplesmente pegar a imagem oficial, montar a pasta de origem, o arquivo de configuração e o encaminhamento de porta. No segundo contentor é necessário instalar e configurar o Xdebug, pelo que terá de ser construído com base no contentor php oficial. Para o mesmo contentor é necessário especificar a diretiva extra_hosts, sem a qual nada funcionará. A configuração do Nginx também é bastante normal:

server {
  listen 80;
  server_name _ !default;
  root /var/www/;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
  index index.html index.htm index.php;
  charset utf-8;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  error_page 404 /index.php;
  location ~ .php$ {
    fastcgi_pass php-fpm:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

É assim que se configura o processamento de scripts PHP no contentor php-fpm e se redireccionam URLs inexistentes para index.php, o que é bastante standard para muitas frameworks e CMS. No Dockerfile do contêiner php-fpm, ele se parece com isso:

Instale o xdebug usando pecl e, em seguida, copie seu arquivo de configuração para o contêiner. Arquivo:

xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.discover_client_host = false
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

O Xdebug 3 para PHP 8 é instalado no contentor, porque a versão antiga já não funciona com esta versão da linguagem, pelo que é utilizada a nova sintaxe de configuração. Bem host, host.docker.internal, que costumava ser prescrito em docker-compose.yaml. A configuração do docker xdebug PHPStorm está agora completa. Em seguida, você pode executar o projeto:

docker-compose up --build

Agora, como na opção anterior, você pode ativar o modo de depuração no navegador, atualizar a página e o depurador se conectará com sucesso ao IDE, apesar de estar sendo executado no Docker