Depurando Projetos PHP com XDebug

O XDebug é uma poderosa ferramenta de depuração, análise de desempenho e cobertura de código para desenvolvimento em PHP. Integrar e usar o XDebug no ambiente local do ServBay pode aumentar significativamente a eficiência do desenvolvimento de projetos PHP e a qualidade do código. Com ele, desenvolvedores conseguem definir breakpoints no código, inspecionar valores de variáveis, rastrear pilhas de chamada de funções, analisar gargalos de desempenho, entre outros, tornando a identificação e resolução de problemas muito mais eficaz.

O que é o XDebug

O XDebug é uma extensão desenvolvida para PHP que oferece recursos avançados de depuração e análise. Ele suporta depuração remota (geralmente via protocolo DBGp), definição de breakpoints, execução passo a passo, inspeção de variáveis, rastreamento de pilha de chamadas de funções, análise de desempenho de scripts (Profiling) e geração de relatórios de cobertura de código (Coverage). Com o XDebug, desenvolvedores obtêm uma visão aprofundada do fluxo de execução e estado do código, facilitando a identificação e correção de bugs.

O XDebug suporta diversos modos de operação, sendo o mais utilizado o modo debug, destinado à depuração interativa com breakpoints.

Como habilitar e configurar o XDebug no ServBay

O ServBay já vem com a extensão XDebug pré-instalada para cada versão de PHP suportada. Não é necessário baixar ou compilar manualmente.

1. Habilitar o módulo XDebug: Abra o aplicativo do ServBay. Navegue até Linguagem > PHP, localize a versão do PHP na qual deseja utilizar o XDebug. Em Extensões, encontre o módulo xdebug e assegure-se de que ele esteja "Habilitado". Se não estiver, clique para habilitar. Após habilitar, pode ser necessário reiniciar o serviço PHP-FPM (o ServBay normalmente faz isso automaticamente).

2. Configurar sua IDE: No seu ambiente de desenvolvimento integrado (IDE), como PHPStorm ou VS Code, configure a conexão com o XDebug. Isso normalmente envolve definir a porta de escuta (compatível com o ajuste de XDebug no painel do ServBay) e, quando aplicável, ajustar o mapeamento de caminhos remotos (geralmente desnecessário em ambientes locais do ServBay, a menos que os caminhos do projeto sejam diferentes entre o ServBay e sua máquina).

   Mais detalhes sobre configuração na IDE

   Para etapas detalhadas sobre como configurar o XDebug em IDEs específicas (como PHPStorm, VS Code etc.), consulte a documentação da IDE ou leia o artigo Como ativar o módulo Xdebug do ServBay.

Exemplo prático: Depurando um projeto PHP no ServBay

Vamos demonstrar como depurar um projeto PHP no ServBay usando o XDebug com um projeto de exemplo simples.

1. Configurando um site no ServBay

Primeiro, crie um novo site no ServBay para hospedar nosso projeto de exemplo:

1. No diretório raiz de sites do ServBay, /Applications/ServBay/www/, crie uma nova pasta para o projeto, por exemplo, servbay-xdebug-app.
2. Abra o aplicativo do ServBay e vá para a seção “Sites”.
3. Clique em adicionar novo site e aponte o diretório raiz para /Applications/ServBay/www/servbay-xdebug-app.
4. Defina um domínio local, como servbay-xdebug-app.servbay.demo.
5. Escolha a versão do PHP desejada, garantindo que esteja habilitada e configurada com o XDebug conforme os passos anteriores.
6. Salve e aplique as alterações. O ServBay irá configurar automaticamente o Caddy/Nginx e atualizar o arquivo hosts (ou utilizar o serviço DNS do ServBay).

2. Estrutura e código do projeto de exemplo

No diretório /Applications/ServBay/www/servbay-xdebug-app/, crie os seguintes arquivos e pastas:

servbay-xdebug-app/
├── src/
│   └── Calculator.php
└── index.php

Conteúdo do arquivo src/Calculator.php:

<?php
namespace App;

class Calculator
{
    public function add($a, $b)
    {
        // Defina um breakpoint nesta linha
        return $a + $b;
    }

    public function subtract($a, $b)
    {
        return $a - $b;
    }
}

Conteúdo do arquivo index.php:

<?php
// Supondo que você esteja usando o Composer, aqui é feito o autoload
// Caso não utilize o Composer, ajuste a forma de carregamento conforme necessário
require __DIR__ . '/vendor/autoload.php';

use App\Calculator;

echo "Exemplo de Depuração:\n";

$calculator = new Calculator();
$num1 = 5;
$num2 = 3;

$sum = $calculator->add($num1, $num2);
$difference = $calculator->subtract($num1, $num2);

echo "Soma: " . $sum . "\n";
echo "Diferença: " . $difference . "\n";

echo "Finalizado.\n";
?>

Observação: O comando require __DIR__ . '/vendor/autoload.php'; acima pressupõe o uso do Composer. Caso esteja apenas testando rapidamente, pode remover essa linha e substituir use App\Calculator; por require __DIR__ . '/src/Calculator.php';.

3. Definindo um breakpoint

Abra o arquivo /Applications/ServBay/www/servbay-xdebug-app/src/Calculator.php em sua IDE (por exemplo, PHPStorm). No método add, clique ao lado do número da linha return $a + $b; para definir um breakpoint.

4. Iniciando a sessão de depuração

1. Na sua IDE, ative a escuta para conexões do XDebug. No PHPStorm, isso geralmente é feito clicando no botão “Start Listening for PHP Debug Connections” (representado por um telefone ou um inseto).
2. No navegador, acesse o arquivo index.php no seu site ServBay: https://servbay-xdebug-app.servbay.demo/index.php.
3. Caso o xdebug.start_with_request esteja definido como trigger, assegure-se de adicionar um trigger ao XDebug pelo navegador (por extensão ou manualmente, por exemplo, acessando https://servbay-xdebug-app.servbay.demo/index.php?XDEBUG_TRIGGER=1).

5. Processo de depuração

1. Quando você acessar o index.php e disparar a sessão do XDebug, ele irá automaticamente se conectar à sua IDE e pausar a execução no breakpoint definido.
2. Sua IDE mudará para a visualização de depuração, exibindo o código pausado na linha do breakpoint no método add do arquivo Calculator.php.

6. Inspecionando variáveis

1. No painel de depuração da IDE, será possível ver a linha de código em execução, a pilha de chamadas (Call Stack), os valores das variáveis (Variables), entre outras informações.
2. No painel “Variables”, verifique os valores das variáveis no escopo atual. Por exemplo, você verá que $a tem valor 5 e $b tem valor 3.

7. Execução passo a passo

1. Utilize os botões de execução passo a passo da IDE (geralmente Step Over (F8), Step Into (F7), Step Out (Shift+F8)):
   • Step Over: Executa a linha atual sem entrar em funções chamadas, prosseguindo para a próxima linha.
   • Step Into: Entra na primeira linha de uma função chamada na linha atual.
   • Step Out: Finaliza a execução da função atual e retorna ao ponto de onde ela foi chamada.
2. Com a execução passo a passo, analise linha a linha o fluxo do código e acompanhe as mudanças nos valores das variáveis.

8. Continuando a execução

1. Clique no botão “Resume Program” da IDE (ícone de reprodução verde ou tecla F9) para continuar a execução do programa até o próximo breakpoint ou até finalizar a execução.

9. Conferindo a saída

1. Após a execução do programa, verifique o resultado no navegador (ou no terminal, se estiver depurando via CLI). Neste exemplo, a saída será:

   Exemplo de Depuração:
   Soma: 8
   Diferença: 2
   Finalizado.

Considerações

• Firewall: Certifique-se de que o firewall do seu sistema operacional não está bloqueando a porta de escuta definida pela IDE (padrão: 9003).
• Conflito de portas: Verifique se a porta configurada para o XDebug não está sendo usada por outro aplicativo.
• Impacto na performance: Com xdebug.mode=debug e xdebug.start_with_request=yes, todas as requisições PHP tentarão iniciar a depuração, o que pode impactar a performance do site. Quando não precisar depurar, desative o módulo XDebug ou ajuste xdebug.start_with_request para trigger.
• Depuração de scripts CLI: O XDebug também permite depurar scripts PHP rodando em CLI. Para isso, defina variáveis de ambiente ou use parâmetros específicos no terminal, conforme a documentação oficial do XDebug.
• Versão e configuração da IDE: As etapas e telas podem variar entre versões e IDEs diferentes; consulte sempre a documentação oficial de sua IDE para uma configuração mais detalhada.

Perguntas Frequentes (FAQ)

P: Minha IDE não conecta ao XDebug. O que posso fazer?

R: Confira os seguintes pontos:

1. Assegure-se de que o módulo XDebug está habilitado para a versão de PHP correta no ServBay.
2. Revise as configurações de xdebug.mode, xdebug.client_host, xdebug.client_port no php.ini e garanta que estão compatíveis com os valores configurados na IDE.
3. Se estiver usando xdebug.start_with_request = trigger, confira se o trigger (GET/POST, Cookie ou Header) está definido corretamente.
4. Certifique-se de que o firewall permite tráfego na porta do XDebug.
5. Certifique-se de que sua IDE está ouvindo a porta corretamente.

P: Por que meu site ficou lento após ativar o XDebug?

R: Isso normalmente ocorre quando xdebug.start_with_request está configurado como yes. Nesse modo, cada requisição de PHP tenta iniciar uma sessão de depuração, aumentando o custo de processamento. O ideal é usar o modo trigger, assim o debug só é ativado quando solicitado.

P: Posso depurar requisições AJAX com XDebug?

R: Sim. A depuração de requisições AJAX funciona de forma similar às requisições HTTP tradicionais — basta garantir que o trigger do XDebug esteja incluído (por Cookie ou Header, por exemplo).

P: O XDebug do ServBay é compatível apenas com PHPStorm? E o VS Code ou outros IDEs?

R: Não. O XDebug integrado no ServBay é um módulo padrão do PHP que é compatível com qualquer IDE/editor que suporte o protocolo DBGp, incluindo, mas não restrito a, VS Code (com a extensão PHP Debug), NetBeans, Eclipse, entre outros. O procedimento é similar, bastando configurar a porta de escuta corretamente na IDE.

Conclusão

Com o XDebug integrado ao ServBay, você pode depurar projetos PHP de maneira fácil e eficiente no ambiente local. Aprender as técnicas essenciais de depuração — como breakpoints, inspeção de variáveis e execução passo a passo — eleva sua capacidade de encontrar e resolver problemas e garante qualidade ao código. Aproveite o gerenciamento prático de ambientes do ServBay e torne o XDebug uma ferramenta indispensável no seu fluxo de trabalho PHP. Experimente agora o XDebug no ServBay e leve seu desenvolvimento PHP a um novo patamar!