Como Xdebug Pode Ajudar Você a se Tornar um Desenvolvedor WordPress Melhor

Como qualquer desenvolvedor pode atestar, o código nunca está pronto para a produção após o primeiro rascunho. Uma parte chave do processo de desenvolvimento é a depuração – remover ou alterar todas as partes do seu código que não funcionam.

A extensão Xdebug para PHP é uma maneira popular de erradicar e destruir todos os bugs do seu código.

Um dos grandes aspectos do Xdebug é como ele é flexível. Independentemente da sua framework preferida ou ambiente de desenvolvimento, você conseguirá encontrar uma versão do Xdebug que se encaixa no seu fluxo de trabalho. A partir daí, ter um controle sobre a ferramenta não vai levar muito tempo.

Este tutorial irá analisar o Xdebug em detalhes, incluindo o processo de instalação, integrando-o em sua configuração e uso geral.

Primeiro, vamos lhe dar mais contexto sobre o que é Xdebug e o que ele faz.

Apresentando o Xdebug

Xdebug é uma das extensões mais populares para depurar seu código PHP. Você irá instalá-lo a partir do ambiente escolhido e ele atua como um “depurador de passos”

Em resumo, isto permite que você trabalhe em seu código linha por linha para que você possa passar e ver como o código age e interage dentro do seu programa, assim como investigar sua saída. A partir daí, você pode fazer às mudanças que achar melhor.

Xdebug pode fazer muito mais, no entanto:

• Você pode analisar a performance do seu código usando um conjunto de métricas e visualizações.
• Quando você executa testes de unidade PHP, você pode ver quais suites de código você executa e executa.
• O Xdebug inclui recursos de “tracing”, que irá gravar cada chamada de função em disco. Isto incluirá argumentos, atribuições de variáveis e valores de retorno.
• O Xdebug também faz melhorias no relatório de erros padrão do PHP. Cobriremos mais sobre isso mais tarde.

Dado o conjunto de recursos, há muitas maneiras de usar o Xdebug (e qualquer depurador similar) dentro do seu fluxo de trabalho. Cobriremos na próxima seção.

Por que você quer usar o Xdebug

Muitos desenvolvedores não terão um fluxo de trabalho de depuração dedicado que utilize ferramentas e extensões de terceiros. Isto é porque o PHP inclui seu próprio log de erros rudimentares. Você vai usar comandos como error_log, var_dump, e imprimir para ver os resultados das variáveis e chamadas de funções.

Por exemplo, há muitos trechos que você pode redirecionar para o desenvolvimento de WordPress – Stack Overflow está repleto deles:

function log_me($message) {
  if ( WP_DEBUG === true ) {
      if ( is_array($message) || is_object($message) ) {
          error_log( print_r($message, true) );
      } else {
           error_log( $message );
      }
  }
}

No entanto, há alguns inconvenientes importantes nesta abordagem:

• Primeiro você deve garantir que você habilite os registros de erros para a plataforma com a qual você está trabalhando. Neste caso, você vai querer habilitar WP_DEBUG (mais sobre isso em breve).
• Este exemplo de “dump” debugging oferece menos espaço para investigação do que o debugging passo a passo. Aqui, você só pode emitir o que você definir.

Este último ponto requer muito esforço manual, especialmente se o seu trabalho diário não for como um administrador de sistema. Por exemplo, se você quiser depurar um bloco de código, você pode adicionar seu snippet baseado em uma variável que você definir. Entretanto, ele pode não ser a fonte do problema ou mesmo indicar o que está acontecendo.

Ao invés disso, uma ferramenta como o Xdebug pode trabalhar sua magia para fornecer um escopo maior:

• Você pode “quebrar” seu código em vários pontos durante a execução para ver o que está acontecendo em tempo real.
• Há uma infinidade de métricas, visualizações, ramificações e muito mais para ajudá-lo a determinar o que seu código está fazendo e como ele responde.
• Algumas vezes, você pode até mesmo mudar os valores durante o processo de depuração. Isto oferece imenso valor, mesmo para conjuntos de códigos que funcionam bem. Você pode essencialmente realizar testes manuais de unidade em qualquer ponto.
• Como você usa pontos de interrupção para marcar áreas para depuração, você não precisa trabalhar com snippets dentro do seu código. Isso mantém seu código mais limpo e reduz o número de problemas futuros.

Em geral, usar uma ferramenta como o Xdebug é uma decisão pró-ativa ao invés de uma decisão reativa. Você pode usar a depuração por etapas como parte do processo de desenvolvimento central, muito parecido com a implementação de testes unitários como parte do desenvolvimento orientado por testes (TDD).

Como ativar o registro de erros do PHP

Enquanto você poderia depurar seu código sem um erro específico, muitas vezes é bom saber se um problema ocorre sem ter o Xdebug aberto. Isto lhe dá um ponto de partida para a exploração. Não é estritamente necessário, mas pode ser uma parte útil da sua cadeia.

Para reportar cada erro que surgir, você precisará adicionar uma linha ao topo do arquivo PHP relevante:

error_reporting(E_ALL);

Este é um comando de captura, e você pode conseguir o mesmo usando a função ini_set função:

ini_set('error_reporting', E_ALL);

Isto permite que você altere as configurações dentro do seu arquivo php.ini em uma base projeto a projeto. Enquanto você poderia entrar neste arquivo e fazer uma mudança manual, muitas vezes é uma ideia melhor trabalhar com ini_set para alterar o parâmetro específico:

ini_set('display_errors', '1');

Uma vez que você tenha o relatório de erros ativo definido ao seu gosto, você pode começar a trabalhar com o Xdebug.

Como usar o Xdebug

Nas próximas seções, mostraremos a você como usar o Xdebug, incluindo os passos que você precisará dar para configurar às coisas. Embora não possamos cobrir todos os aspectos da ferramenta, este guia de início rápido o colocará em ação rapidamente.

Primeiro, no entanto, você precisa instalar o Xdebug. Vamos descobrir como fazer isso.

1. Instale o Xdebug para o seu Sistema Operacional (SO)

Como o Xdebug é adaptável a qualquer número de configurações, o processo exato para cada uma delas será ligeiramente diferente. No nível do sistema operacional, há algumas diferenças:

• Windows: Este é um processo de configuração um tanto complicado que envolve o uso de um arquivo PHP existente e um assistente de instalação, então baixando a versão certa para o seu sistema.
• Linux: O método aqui é indiscutivelmente o mais simples: Você pode usar um gerenciador de pacotes para instalar o Xdebug, ou a Biblioteca da Comunidade de Extensão PHP (PECL).
• Mac: Este método também é simples: Uma vez instalada a PECL, você pode rodar pecl install xdebug a partir de uma instância do Terminal. Você também precisará ter às ferramentas de linha de comando XCode e PHP instaladas em seu sistema.

No entanto, a maioria dos usuários não vão querer ficar com uma instância de Xdebug em nível de sistema. Ao invés disso, você vai querer integrá-la em seu próprio ambiente de desenvolvimento.

2. Integre o Xdebug ao seu ambiente de desenvolvimento

Uma vez instalado o Xdebug para o seu sistema operacional, você deve conectá-lo ao seu ambiente.

Há tantos sistemas e ferramentas suportados aqui que não podemos entrar em todos eles. Mais tarde, lhe ofereceremos instruções para DevKinsta e PhpStorm. Mesmo assim, há muitos outros ambientes populares para escolher. Abaixo estão algumas das nossas principais recomendações.

Varying Vagrant Vagrants (VVV)

VVV é um dos ambientes nomeados no site Make WordPress:

A boa notícia é que o VVV já inclui uma versão do Xdebug, mas você precisa ativá-lo. Você pode fazer isso usando o Secure Shell (SSH) dentro de uma janela do Terminal:

vagrant ssh -c "switch_php_debugmod xdebug"

No entanto, há um pouco de sucesso no desempenho, e você precisará ativar essa opção novamente se você fornecer seus sites.

Laravel Valet

Para alguns usuários, Laravel Valet representa um ambiente de desenvolvimento web quase perfeito. Melhor ainda, você pode integrar o Xdebug com ele.

Para fazer isso, você precisará criar um arquivo de configuração para o depurador. Você pode encontrar seu próprio caminho usando php --ini na linha de comando, que irá retornar alguns caminhos de arquivo diferentes:

A seguir, crie um novo arquivo xdebug.ini no caminho para arquivos .ini adicionais. Em nosso exemplo, ele está em /opt/homebrew/etc/php/7.4/conf.d.

Assim que você abrir este novo arquivo, abra também o caminho para o arquivo de configuração carregado (seu arquivo php.ini principal). Com ambos abertos, adicione o seguinte ao rodapé:

• php.ini: zend_extension="xdebug.so"
• xdebug.ini: xdebug.mode=debug

Uma vez que você salvou suas mudanças, execute valet restart do Terminal, então adicione phpinfo(); exit; a um dos arquivos do seu site. Você vai querer verificar se isso funciona através de um rápido carregamento de página no navegador.

Note que você pode precisar reiniciar o PHP usando sudo brew services restart php assim como verificar se a instalação do Xdebug em seu sistema está correta usando php --info | grep xdebug. Você vai notar as linhas específicas do Xdebug na saída:

A partir daqui, você pode procurar incorporar o Xdebug em seu editor de códigos de escolha.

XAMPP

Assim como o Valet, existem algumas partes do processo para o XAMPP. Entretanto, as versões Windows e macOS têm dois processos diferentes.

Comece instalando o XAMPP, então execute uma verificação rápida para ver se o arquivo php_xdebug.dll (Windows) ou xdebug.so file (macOS) existe em seu sistema:

Se o arquivo existir, você pode passar para a configuração. Caso contrário, você precisará primeiro baixar ou o binário certo para Windows – um arquivo de 64 bits para sua versão preferida do PHP – ou instalar mais algumas dependências se você estiver em um Mac.

Para Windows, renomeie o arquivo DLL php_xdebug.dll, então mova-o para o caminho do arquivo xamppphpext. Em seguida, abra o arquivo xamppphpphp.ini no editor de código de sua preferência e adicione o seguinte:

output_buffering = Off

Na seção [XDebug], adicione às próximas três linhas:

zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger

Assim que você salvar suas mudanças, reinicie o Apache e teste para Xdebug.

Para Mac, você vai querer garantir que você instale às ferramentas de linha de comando Xcode usando xcode-select --install em uma instância do Terminal. Depois disso, há três pacotes que você vai querer instalar usando o Homebrew:

brew install autoconf automake libtool

Em alguns casos, você também precisará reinstalar o XAMPP para obter tanto o programa principal quanto os “Arquivos do Desenvolvedor” Você deve conseguir reinstalar somente estes arquivos, mas você vai querer realizar um backup da sua configuração existente primeiro.

Em seguida, navegue para o download da pasta de fontes Xdebug em seu sistema e descompacte o arquivo TGZ. Dentro de uma janela do Terminal, navegue até aquele diretório e execute o seguinte:

phpize
pecl install xdebug

Note que você pode precisar usar sudo aqui também. Daqui, você pode editar o arquivo php.ini do XAMPP. Para a maioria das instalações macOS, você o encontrará em /Applications/XAMPP/xamppfiles/etc/php.ini. Dentro deste diretório, você também encontrará o caminho para o seu arquivo xdebug.so – anote isto e use-o no lugar do espaço reservado ao caminho do arquivo para este snippet:

[xdebug]
zend_extension=/path/to/xdebug.so
xdebug.mode=develop,degug
xdebug.start_with_request=yes

Para testar se isso funciona, crie um novo arquivo xdebug_info.php no diretório principal do htdocs XAMPP. Dentro, adicione o seguinte:

<?php
xdebug_info();

…depois atualize o Apache e teste o Xdebug no navegador.

Usando PhpStorm com Xdebug

Assim que você instalar o Xdebug através do sistema operacional e seu ambiente de desenvolvimento, você também precisará visualizar o depurador em si. Você fará isso através do seu editor de código escolhido ou ambiente de desenvolvimento integrado (IDE). Como no seu ambiente, há tantos para escolher, e cada um pode ter uma abordagem diferente.

Dito isto, muitos desenvolvedores optam por usar o PhpStorm da JetBrains. Na verdade, o PhpStorm oferece “assistência WordPress-aware” – e é uma escolha popular por muitas outras razões, também.

O site JetBrains inclui instruções completas sobre como conectar Xdebug e PhpStorm, mas iremos revisá-las aqui.

Primeiro, navegue até a página Languages & Frameworks > PHP no painel de Preferences. Aqui, abra o menu More Items do kebab ao lado do campo suspenso CLI Interpreter:

Isto mostrará mais alguns detalhes sobre sua versão PHP e intérprete. Se você clicar na elipse Mais itens ao lado da opção Configuration file, você verá os caminhos completos para o seu arquivo php.ini:

Você estará trabalhando com este arquivo PHP ao lado para continuar o processo de configuração.

Trabalhando no arquivo php.ini

A primeira tarefa aqui é editar qualquer linha que tenha impacto em como o Xdebug irá trabalhar com o PhpStorm.

Dentro do arquivo php.ini, encontre as seguintes linhas e apague ou comente-as:

zend_extension=<path_to_zend_debugger>
zend_extension=<path_to_zend_optimizer>

Estas linhas não estarão presentes em todos os casos, então não se assuste caso você não estiver vendo.

A seguir, adicione o seguinte ao arquivo:

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"

Há algumas coisas a se notar sobre este conjunto de códigos:

• Você já pode ter uma seção [xdebug], neste caso você pode omitir a primeira designação.
• A entrada zend_extension pode precisar que você adicione o caminho completo do xdebug.so para se conectar.
• Embora possa parecer um espaço reservado, o parâmetro xdebug.client_port é como você irá configurá-lo dentro do seu código.

Uma vez que você adicione estes, salve e feche o arquivo, então teste a versão PHP a partir da linha de comando (usando php --version):

Se você tiver uma versão funcional do Xdebug, ela aparecerá como uma das extensões do PHP. Você também pode adicionar phpinfo(); a um novo arquivo e testar isso no navegador.

Isso é tudo que você precisa fazer para ter o Xdebug funcionando como seu depurador padrão com o PhpStorm. O passo final antes de usá-lo é instalar uma extensão de ajuda do navegador.

Instalando uma extensão de ajuda do navegador

A conexão chave final que você precisará fazer é entre seu navegador e PhpStorm, realizada ativando a depuração passo a passo no servidor. Enquanto você poderia fazer isso a partir da linha de comando usando valores especiais GET ou POST, é mais simples usar uma extensão.

Recomendamos a utilização da extensão dedicada do Xdebug Helper. Você pode instalá-la no seu navegador de sua escolha:

• Xdebug Helper para Chrome/Cromium/Brave
• Xdebug Helper para Firefox

Se você quiser explorar outras extensões, o site JetBrains oferece algumas opções adicionais para os navegadores mais populares.

Uma vez instalada a extensão do seu navegador escolhido, você não deve ter que ajustar nenhuma outra configuração. A partir daqui, você pode começar a usar o Xdebug com o PhpStorm.

Usando o Xdebug

Enquanto usaremos PhpStorm aqui, você verá um layout similar e uma interface entre diferentes IDEs – embora também haja algumas diferenças óbvias.

Há alguns conceitos que se combinam para formar toda a experiência de depuração:

• Breakpoints: Estes são os pontos em que Xdebug vai parar a fim de permitir que você inspecione a saída. Você pode definir quantos você quiser.
• Ouvindo as conexões: Você pode ligar e desligar isso, embora a maioria dos desenvolvedores sempre deixe ligado.
• A tela de depuração: A maior parte do seu tempo será gasto na interface de depuração – é onde você trabalhará com às várias linhas de código, variáveis e parâmetros.

O primeiro passo é ativar a escuta – você não conseguirá depurar nada sem ela. Para fazer isso, clique na opção Run > Start Listening for PHP Debug Connections na barra de ferramentas:

Como alternativa, você pode clicar no ícone “telefone” na barra de ferramentas do PhpStorm:

Qualquer uma destas opções iniciará a escuta para conexões.

A partir daqui, você pode começar a definir breakpoints no editor de código. Um ponto vermelho indica um breakpoint, que você pode clicar para ativar:

Quando você quiser depurar seu código, a maneira mais direta é começar a ouvir, definir pontos de interrupção e depois ir para a página específica em seu navegador. Localize o ícone para sua extensão no navegador, então clique nele e selecione a opção “Debug”:

Isto abrirá o depurador no PhpStorm e dará às boas ou más notícias:

Se você clicar com o botão direito do mouse nos vários valores, atributos, parâmetros e variáveis, você conseguirá acessar um menu de contexto adicional. Isto lhe dá bastante escopo extra para testar e depurar seu código:

Por exemplo, você poderia definir valores diferentes para variáveis ao longo do caminho. Isto pode ser uma tentativa deliberada de quebrar seu código e ver o que acontece, ou pode ser uma maneira de testar o código que já precisa de uma correção. De qualquer forma, isto lhe dá um método fantástico para depurar seu código sem ter que alterá-lo primeiro.

Como a Kinsta ajuda você a depurar seu site WordPress

O WordPress vem com seu próprio conjunto de opções de depuração através do WP_DEBUG e outras ferramentas, como o Query Monitor. Estas permitem um modo no qual você começará a ver mensagens de erro previamente ocultas em todo o seu site e painel de controle. A partir daí, você pode começar a descobrir qual é o problema.

Você também pode salvar essas mensagens de erro usando WP_DEBUG_LOG, o que lhe dá uma maneira de documentar os problemas com o seu site. Cobrimos como configurar isso em outro artigo no blog. Isto é muito fácil para configurar através do seu painel MyKinsta (e da tela Sites > Ferramentas ):

Se você emparelhar isto com a ferramenta gratuita de ambiente local DevKinsta, você também terá uma maneira de habilitar e desabilitar WP_DEBUG para cada site que você rodar:

Isto significa que você pode pegar erros em seu site durante o desenvolvimento, e certifique-se de que eles não cheguem ao seu site de produção. Estes modos também são fáceis de desativar – vitais tanto para a segurança do site quanto para a segurança do usuário.

Todos os planos Kinsta também vêm com a ferramenta incorporada Kinsta APM, sendo nossa ferramenta de monitoramento de desempenho projetada sob medida para sites WordPress.

Lista de comandos

Antes de encerrarmos este artigo, devemos mencionar os atalhos.

Como muitas outras peças de software, há várias maneiras de navegar pelo Xdebug (e PhpStorm) usando apenas o teclado. Na verdade, você poderia até usar a linha de comando para depurar scripts PHP.

Uma vez que o Xdebug esteja pronto e funcionando, você pode usar os seguintes comandos para se orientar:

Enquanto seu editor de código específico terá seus próprios atalhos dedicados, o foco aqui é o PhpStorm. Dê uma olhada nesta tabela de atalhos de teclado para usar o Xdebug com PhpStorm:

Felizmente, não há muito o que memorizar aqui. Você deve abrir o depurador, definir breakpoints por linha, ouvir às conexões e executar seus scripts.

Entretanto, se você precisar de um atalho para uma determinada tarefa, você pode usar o comando PhpStorm Find Action:

Quando você começar a digitar neste espaço, será mostrada a você uma lista dinâmica de comandos e atalhos relacionados. Você também pode encontrar uma versão PDF de todos os atalhos de teclado através do menu Help > Keyboard Shortcuts PDF.

Se você quiser dar mais uma olhada em tempo real nos atalhos enquanto trabalha com o mouse, a JetBrains fornece o plugin Key Promoter X:

Esta útil ferramenta exibirá notificações da sua última ação executada, com seu atalho de teclado relacionado. Assim que você aprender e usar os atalhos, você pode desconectar este plugin e restaurar aquela propriedade valioso para Á sua tela.

Resumo

A prática da depuração (debugging) tem vindo muito longe do seu humilde começo; agora abrange um escopo muito mais amplo do que seus progenitores poderiam ter imaginado. Para realizar um trabalho completo quando se trata de corrigir seu código PHP, você precisará usar uma ferramenta competente. Há muitas extensões e ferramentas excelentes para escolher, mas Xdebug é um frontrunner discutível.

Como vimos, Xdebug pode se adaptar até mesmo aos gostos mais ecléticos dos editores de código, e é especialmente ótimo quando emparelhado com PhpStorm. No entanto, independentemente da sua configuração, muitas vezes haverá uma versão do Xdebug para atender às suas necessidades. No geral, é uma ferramenta poderosa, flexível e intuitiva de usar.

Você acha que o Xdebug merece seus altos elogios, ou existe outra ferramenta de depuração que você prefere? Nos deixe saber na seção de comentários abaixo!

Salman Ravoof

Salman Ravoof is a self-taught web developer, writer, creator, and a huge admirer of Free and Open Source Software (FOSS). Besides tech, he's excited by science, philosophy, photography, arts, cats, and food. Learn more about him on his website, and connect with Salman on Twitter.

• Site
• LinkedIn
• Twitter