Configurando o Xdebug em editores da Jetbrains

Introdução

Estava eu, estudando novamente o framework Laravel do mundo PHP - depois de algum tempo muito focado no Java e usando o Intellij como editor de código favorito – e percebi uma coisa: a utilização do debug não é bem explicada... vocês já perceberam isso? No meu caso, o debug foi, e é, imprescindível quando estou no Java. Portanto, partindo dessa percepção inicial, este artigo mostrará como podemos fazer debug da aplicação Laravel nos editores da Jetbrains. Bora lá?

Alguns pontos importantes a serem destacados

O primeiro ponto que é preciso destacar é que daqui em diante vamos nos referir aos editores Intellij Idea ou PHP Storm apenas como como “editor”, já que o que vamos abordar neste artigo funciona tanto para o Intellij Idea quanto para o PHP Storm.

Outro ponto importante é que vamos precisar instalar apenas uma ferramenta no sistema operacional. Durante este artigo vamos utilizar o Linux, mais especificamente o Ubuntu 20.04, que é o sistema que utilizo atualmente, mas você pode utilizar os links abaixo, para realizar as instalações no Windows e ou no macOS respectivamente:

Requisitos

Antes de irmos para o debug de fato precisamos cumprir alguns requisitos.

Xdebug

O primeiro requisito que precisamos é instalar e configurar o Xdebug que é, segundo os próprios desenvolvedores, “uma extensão para PHP e fornece uma variedade de recursos para melhorar a experiência de desenvolvimento PHP” bem como o Step Debugging (que significa “depuração em etapas”). Ou seja, podemos percorrer nosso código PHP e verificar valores de variáveis, dentre outras coisas durante a execução do código, o que é de extrema importância quando temos algum comportamento estranho, mas não estamos conseguindo identificar a causa real do problema, para que possamos corrigir.

Então, para fazer a instalação da versão 8 do xdebug (que é para o PHP 8) basta atualizar os repositórios disponibilizados no Ubuntu, usando o seguinte comando:

sudo apt update

E em seguida fazer a instalação usando o seguinte comando:

sudo apt install php-xdebug

Porém se você não está usando a versão 8 do PHP você provavelmente, deve estar utilizando o PPA do Ondřej Surý e assim como eu, deve utilizar o seguinte comando:

sudo apt install php7.4-xdebug

Agora precisamos fazer uma configuração simples, como o Xdebug é uma extensão do PHP ele tem seu próprio arquivo de configuração, o caminho desse arquivo é:

/etc/php/7.4/mods-available/xdebug.ini

Então, para editar podemos utilizar o nosso editor de preferência, no terminal sempre uso o nano. Utilizamos então o seguinte comando:

sudo nano /etc/php/7.4/mods-available/xdebug.ini

Quando abrir o arquivo, possivelmente ele só terá a seguinte linha:

zend_extension=xdebug.so

Logo abaixo da mesma devemos inserir as seguintes linhas:

xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.discover_client_host=1

Pronto, podemos sair e salvar o arquivo e com isso terminamos nossa configuração do Xdebug.

Extensões

A própria documentação do editor fala que precisamos instalar duas extensões no editor. Porém, uma delas é paga e por isso vamos utilizar apenas uma que é gratuita.

Então, precisamos instalar essa extensão Laravel no editor para podermos continuar.

Para isso, podemos ir no link acima e clicar no botão “Install to <Nome e versão do seu editor>” que já deve ser feita a instalação no seu editor.

Caso não consiga dessa forma, você pode abrir as configurações do editor indo na opção “File” e depois na opção “Settings” e acessar a seção “Plugins” e então pesquisar por “Laravel” e em seguida clicar no botão “Install” do respectivo plugin, e em seguida reiniciar o editor.

Extensão navegador

Para fazer o debug de uma aplicação PHP também precisamos instalar uma extensão no navegador onde vamos acessar a aplicação. Para isso, pesquise e instale a extensão Xdebug helper no seu navegador preferencial.

Projeto

Precisamos também estar com o projeto importado no editor para darmos continuidade no restante da configuração.

Configurando a execução em modo debug

Agora que temos tudo disposto, podemos partir para a configuração de fato no editor para usar o debug.

Criar configuração de execução:

No menu principal do editor precisamos acessar a opção “Run | Edit Configurations” e em seguida, clicar no botão de adicionar (“ + ”) e escolher a opção “PHP Script”:

Alt: print de tela do menu principal do Intellij Idea em fundo preto, com a seleção da opção “Edit Configurations” em formato de barra de rolagem e destaque em retângulo vermelho na opção “Edit Configurations” representando as etapas de acesso.

Alt: print de tela “Run/Debug Configurations” do Intellij Idea em fundo preto, com a seleção da opção “PHP Server” selecionada em azul representando a criação de uma nova configuração de execução.

Configurando a execução:

Agora podemos colocar um nome de nossa preferência no campo “Name”, e na seção “Configuration” devemos colocar no campo “File” o caminho completo do arquivo “artisan” do nosso projeto ou então usar o botão “Browse…” para ir até o arquivo. E, por fim, devemos colocar no campo “Arguments” a palavra serve. Agora podemos clicar no botão “Apply” e depois em “OK”. Veja a imagem abaixo:

Explicando melhor, com essa configuração estamos dizendo ao editor para ele executar um script PHP, ou seja, ele vai usar o Built-in Web Server do PHP (php) para subir a aplicação, e o script de fato que ele vai usar é o artisan com o argumento serve. Por fim, ele vai estar executando o comando simples para subir a aplicação:

php artisan serve

Iniciando o ouvinte de conexões de debug para PHP:

Agora precisamos clicar no botão “Start Listening for PHP Debug Connections” no menu principal do editor, essa opção vai fazer com que o editor escute uma conexão de debug vinda do Xdebug.

Alt: print de tela do menu principal do Intellij Idea em fundo preto, com destaque em retângulo vermelho na opção “Start Listening for PHP Debug Connections” representando a ativação do ouvinte de conexões de debug para PHP.

Adicionar breakpoint:

Agora podemos adicionar um breakpoint em qualquer parte do projeto. Pode ser no arquivo index.php na pasta public do projeto, nas primeiras linhas apenas para teste.

Alt: print de tela de edição do editor com o arquivo “index.php” aberto e com um círculo preenchido em vermelho bem como a linha 06 toda marcada em vermelho representando um breakpoint no arquivo.

Executar e acessar aplicação:

Agora podemos iniciar a aplicação em modo debug clicando na opção “Debug ‘PHP Server’” no menu principal e então acessar a aplicação pelo navegador e a execução vai para no nosso breakpoint.

Alt: print de tela de edição do editor com o arquivo “index.php” aberto e com um círculo preenchido em vermelho na linha 06 e toda a linha marcada em azul o script parado no ponto demarcado pelo breakpoint esperando a liberação do restante da execução.

Conclusão

Assim, podemos ter clareza de como instalar e configurar Xdebug, bem como as extensões necessárias nos editores e no navegador. Com isso conseguimos utilizar o debug nos editores da Jetbrains com Xdebug por baixo do panos, e atingimos um ambiente similar ao Java nos editores, que pra mim, é muito mais produtivo e rápido. E, de bônus, podemos utilizá-lo para outros frameworks do PHP ou até um script simples PHP.

Gostou do artigo e quer aprender mais sobre PHP e Laravel? Aqui na Alura temos a formação PHP que mostra muito mais sobre PHP, Laravel, Lumen. Até a próxima!