Como habilitar e configurar o módulo Xdebug no ServBay

O ServBay é um ambiente local de desenvolvimento web poderoso e pré-integrado com a ferramenta de depuração e análise Xdebug para desenvolvedores PHP. Ao habilitar o Xdebug, é possível aumentar significativamente a eficiência no desenvolvimento de aplicações PHP, facilitando tarefas como depuração de código, análise de desempenho e checagem de cobertura de testes. Este artigo apresenta em detalhes como ativar e configurar o Xdebug no ServBay, além de guiar a integração com as principais IDEs do mercado.

Visão geral do módulo Xdebug

O Xdebug é uma extensão PHP repleta de recursos, desenvolvida especificamente para depuração e análise de código PHP. Com o Xdebug já integrado ao ServBay, você não precisa compilar ou instalar manualmente, tornando o processo de ativação e configuração muito mais simples.

Principais funcionalidades do Xdebug

• Depuração com breakpoint: Permite definir breakpoints em linhas específicas do código, pausando a execução do programa e possibilitando a análise de variáveis e da pilha de chamadas, além da execução linha a linha.
• Depuração passo a passo: Suporta execução passo a passo (Passar - Step Over), entrada em funções (Step Into) e saída de funções (Step Out), facilitando o rastreamento do fluxo do programa.
• Monitoramento de variáveis: Exibição em tempo real dos valores de variáveis locais e globais durante o debug.
• Rastreamento de pilha: Exibe informações detalhadas da pilha de chamadas em caso de erros ou exceções, ajudando a localizar rapidamente a origem de problemas.
• Análise de desempenho (Profiling): Gera relatórios detalhados do desempenho do código, auxiliando na identificação de gargalos.
• Cobertura de código (Code Coverage): Mede a porcentagem do código coberta pelos testes, fundamental para avaliar a efetividade dos testes implementados.

Versões do Xdebug integradas ao ServBay e mapeamento de portas

O ServBay vem com o módulo Xdebug pré-instalado para diferentes versões do PHP. Importante: cada versão do PHP utiliza uma porta de escuta do Xdebug exclusiva, associada à versão do PHP — esse detalhe é essencial na configuração do depurador na IDE.

Versão PHP	Versão Xdebug pré-instalada	Porta de escuta padrão Xdebug
PHP 5.6	Xdebug 2.5.5	39056
PHP 7.0	Xdebug 2.5.5	39070
PHP 7.1	Xdebug 2.5.5	39071
PHP 7.2	Xdebug 3.1.6	39072
PHP 7.3	Xdebug 3.1.6	39073
PHP 7.4	Xdebug 3.1.6	39074
PHP 8.0	Xdebug 3.3.1	39080
PHP 8.1	Xdebug 3.4.0	39081
PHP 8.2	Xdebug 3.4.0	39082
PHP 8.3	Xdebug 3.4.0	39083
PHP 8.4	Xdebug 3.4.0	39084
PHP 8.5	Xdebug 3.4.0	39085

Regra de portas

A regra padrão para a porta de escuta do Xdebug é 39000 + versão secundária do PHP. Por exemplo, para o PHP 8.3, a porta é 39000 + 83 = 39083; para o PHP 7.4, é 39000 + 74 = 39074. Compreender esta regra ajuda a identificar rapidamente a porta do Xdebug para diferentes versões do PHP.

Como habilitar o módulo Xdebug

Ativar o Xdebug no ServBay é extremamente prático, sendo recomendado o uso da interface gráfica (GUI) do ServBay. Caso prefira, também é possível editar o arquivo de configuração manualmente.

Habilitando o Xdebug pela interface gráfica do ServBay

Este é o método mais simples e rápido.

1. Abra a interface do ServBay.
2. No menu lateral, selecione Idiomas (Languages).
3. Expanda a seção PHP e escolha a versão do PHP desejada para habilitar o Xdebug, por exemplo, PHP 8.3.
4. Clique no botão Extensões ao lado da versão escolhida.
5. Na lista de extensões exibida, localize o módulo Xdebug.
6. Ative o Xdebug alternando o botão ao lado do módulo de desligado para ligado.
7. Modifique os parâmetros conforme necessário.
8. Clique no botão Salvar no rodapé da interface.
9. O ServBay irá reiniciar automaticamente o processo PHP e carregar o módulo.

Ilustração: Ativando o Xdebug nas Extensões

Como verificar se o Xdebug foi carregado com sucesso

A forma mais confiável é verificar as informações do PHP usando a função phpinfo().

1. No diretório raiz do site ServBay (padrão /Applications/ServBay/www), crie um arquivo PHP simples, por exemplo, phpinfo.php.
2. No arquivo phpinfo.php, insira o conteúdo:

   <?php
   phpinfo();
   ?>

3. Acesse este arquivo pelo seu navegador, exemplo: https://servbay.demo/phpinfo.php (lembre-se de substituir servbay.demo pelo domínio do seu site configurado no ServBay).
4. Na página gerada pelo phpinfo, busque por "Xdebug". Se o Xdebug estiver carregado corretamente, você verá uma seção independente "Xdebug" com informações de versão e parâmetros de configuração.

Ilustração: Localize informações do Xdebug na saída do phpinfo

Configurando o Xdebug para depuração nas IDEs

Ativar o Xdebug é o primeiro passo, mas para usar breakpoints nas IDEs, é necessário configurar o interpretador PHP, o depurador e o mapeamento de caminhos. Veja como fazer isso nas IDEs PHPStorm e Visual Studio Code (VS Code):

Configurando o Xdebug no PHPStorm

O PHPStorm tem suporte nativo e avançado ao Xdebug.

1. Abra as configurações do PHPStorm: Inicie o PHPStorm e acesse Arquivo -> Configurações (Windows/Linux) ou PHPStorm -> Preferências (macOS).

2. Configure o interpretador CLI (PHP):

   • Navegue até Languages & Frameworks -> PHP.
   • Em CLI Interpreter, clique no botão ... ao lado.
   • Na janela aberta, clique no + para adicionar um interpretador local.
   • Selecione o caminho do executável PHP da versão correspondente no ServBay, por exemplo, /Applications/ServBay/package/php/8.3/8.3.7/bin/php (verifique a versão conforme sua instalação).
   • O PHPStorm detecta automaticamente versão e extensões, incluindo o Xdebug.
   • Clique em OK para salvar. Ilustração: Configurando o CLI do PHP do ServBay no PHPStorm

3. Configure os parâmetros de depuração do Xdebug:

   • Navegue até Languages & Frameworks -> PHP -> Debug.
   • Em Xdebug, ajuste o campo Debug Port para a porta correspondente à versão habilitada no ServBay (ex.: PHP 8.3 usa 39083). Certifique-se de que esta porta seja igual ao valor configurado em xdebug.client_port.
   • Marque a opção Can accept external connections.
   • Clique em Apply e depois em OK. Ilustração: Parâmetro da porta de escuta Xdebug no PHPStorm

4. Configure o mapeamento do servidor web PHP:

   • Navegue até Languages & Frameworks -> PHP -> Servers.
   • Clique no + e adicione uma nova configuração de servidor.
   • Defina um nome de servidor (exemplo: ServBay Localhost).
   • Defina o host como o domínio do seu site do ServBay (exemplo: servbay.demo).
   • Defina a porta utilizada pelo site, normalmente 443 (HTTPS) ou 80 (HTTP).
   • Escolha Xdebug como depurador.
   • Marque a opção Use path mappings.
   • Configure o mapeamento de caminhos locais (exemplo: /Applications/ServBay/www/meuprojeto) para os caminhos do servidor (geralmente /). Se acessar por https://servbay.demo/, o caminho local /Applications/ServBay/www/meuprojeto deve mapear para / no servidor. Se usar o subdomínio https://meuprojeto.servbay.demo/, o caminho local também mapeará para /. O mapeamento correto é fundamental para o Xdebug funcionar.
   • Clique em OK para concluir. Ilustração: Como configurar servidor e mapeamento de caminho no PHPStorm

5. Inicie a sessão de depuração:

   • Abra o arquivo PHP do seu projeto no PHPStorm.
   • Clique ao lado da linha do código para inserir um breakpoint (círculo vermelho).
   • Clique no botão Start Listening for PHP Debug Connections na barra de ferramentas do PHPStorm (ícone de inseto). O ícone ficará verde, indicando que o PHPStorm está ouvindo conexões Xdebug.
   • No navegador, acesse sua aplicação PHP (exemplo: https://servbay.demo/index.php).
   • Se tudo estiver correto, o Xdebug conectará ao PHPStorm e pausará no breakpoint, permitindo depurar o código diretamente pela IDE. Ilustração: Iniciando a escuta do Xdebug no PHPStorm

Configurando o Xdebug no Visual Studio Code (VS Code)

O VS Code é um editor de código popular que, com a extensão adequada, oferece ótima integração com o Xdebug.

1. Instale a extensão PHP Debug:

   • Abra o VS Code.
   • Acesse o painel de extensões (Ctrl+Shift+X ou Cmd+Shift+X).
   • Pesquise por "PHP Debug" e instale a extensão de Felix Becker.

2. Configure o arquivo launch.json:

   • Abra a pasta do projeto PHP.
   • Vá até o painel "Executar e Depurar" (Ctrl+Shift+D ou Cmd+Shift+D).
   • Clique no ícone de engrenagem no topo e escolha "PHP". Isso criará um arquivo launch.json na pasta .vscode do projeto.
   • Edite o arquivo launch.json. Certifique-se de que a configuração "Listen for Xdebug" tem o parâmetro port igual ao da sua versão do PHP no ServBay (exemplo: PHP 8.3, porta 39083).
   • Mapeamento de caminhos (Path Mapping): Este é crucial para o debug no VS Code. No arquivo launch.json, localize ou adicione o parâmetro pathMappings para mapear os diretórios do servidor (ServBay) aos do seu computador.

     {
         "version": "0.2.0",
         "configurations": [
             {
                 "name": "Listen for Xdebug",
                 "type": "php",
                 "request": "launch",
                 "port": 39083, // Altere conforme sua versão do PHP
                 "pathMappings": {
                     // Mapeia o caminho dos projetos no ServBay para o seu sistema local
                     // Exemplo: se o projeto está em /Applications/ServBay/www/meuprojeto
                     // e é acessado via https://servbay.demo/, '/' se refere ao diretório raiz do projeto local
                     "/": "${workspaceRoot}"
                     // Para projetos em /Applications/ServBay/www/meuprojeto
                     // com acesso via subdomínio https://meuprojeto.servbay.demo/
                     // o mapeamento '/' também aponta para a raiz local do projeto
                     // "/": "${workspaceRoot}" // Válido também
                 }
             },
             {
                 "name": "Launch currently open script",
                 "type": "php",
                 "request": "launch",
                 "program": "${file}",
                 "cwd": "${fileDirname}",
                 "port": 39083 // Altere conforme sua versão do PHP
             }
         ]
     }

     Ajuste o pathMappings de acordo com a estrutura do seu projeto e configuração no ServBay. ${workspaceRoot} geralmente corresponde à raiz do projeto aberto no VS Code.

3. Inicie a sessão de depuração:

   • Abra o arquivo PHP desejado no VS Code.
   • Clique ao lado do número da linha para definir um breakpoint.
   • No painel "Executar e Depurar" (Ctrl+Shift+D ou Cmd+Shift+D), selecione "Listen for Xdebug".
   • Clique no botão verde de início de depuração. A barra de status do VS Code ficará laranja, indicando que está ouvindo conexões do Xdebug.
   • Acesse sua aplicação PHP pelo navegador. Se estiver tudo certo, o Xdebug conectará ao VS Code e pausará no breakpoint.

Perguntas Frequentes (FAQ)

• Q: O módulo Xdebug não aparece no phpinfo()?

  • A: Confira se o Xdebug foi ativado no GUI do ServBay ou manualmente no xdebug.ini.
  • Certifique-se de reiniciar o serviço PHP correspondente após qualquer alteração.
  • Verifique se o caminho do arquivo xdebug.ini está correto e se a linha zend_extension = xdebug.so não está comentada.
  • Consulte os logs do ServBay (/Applications/ServBay/logs/php/<versão>/error.log) para eventuais erros ao carregar o Xdebug.

• Q: Mesmo com breakpoint na IDE, o programa não para?

  • A: Certifique-se de que a IDE está ouvindo conexões do Xdebug (o ícone de inseto do PHPStorm fica verde; a barra do VS Code fica laranja).
  • Verifique se a porta do Xdebug na IDE coincide com o valor de xdebug.client_port do ServBay e com a porta padrão da versão do PHP em uso.
  • Verifique se o mapeamento de caminhos está correto, garantindo que os arquivos do servidor sejam corretamente associados aos arquivos do seu projeto local — esse é um dos problemas de configuração mais comuns.
  • Revise as configurações do firewall e certifique-se de que nenhuma regra está bloqueando a porta do Xdebug (padrão 390xx).
  • Caso utilize xdebug.start_with_request=trigger no xdebug.ini, certifique-se de incluir o gatilho no navegador ou requisição (por exemplo, usando a extensão Xdebug Helper ou adicionando ?XDEBUG_TRIGGER=1 à URL).

• Q: A conexão do Xdebug é interrompida após algum tempo?

  • A: Revise os parâmetros xdebug.remote_autostart ou xdebug.start_with_request no xdebug.ini. Se estiverem como yes, o debug será iniciado em todas as requisições — o recomendado é o modo trigger.
  • Revise a configuração de timeout (tempo limite) da sua IDE de depuração.

Conclusão

Graças à integração e ao fluxo de configuração simplificado, o ServBay facilita imensamente o uso do Xdebug por desenvolvedores PHP. Seja pela interface gráfica amigável, seja pela edição manual de arquivos, você pode rapidamente ativar o Xdebug em diferentes versões do PHP no ServBay. Integrando com IDEs poderosas como PHPStorm ou VS Code, é possível depurar, otimizar e garantir a qualidade do seu código de forma muito mais produtiva. Dominar o uso do Xdebug no ServBay certamente vai impulsionar o seu fluxo de trabalho no desenvolvimento PHP local.