XDebug: ferramenta de debug e profiling

Conhecendo o XDebug - Apresentação

Olá, pessoal. Sejam muito bem-vindos à Alura. Eu sou Vinicius Dias e vou guiá-los neste treinamento de XDebug.

Começaremos o curso conhecendo o XDebug e fazendo sua instalação, que será realizada tanto no ambiente Windows quanto no Linux (por meio do WSL), e até comentaremos sobre o Docker. Vamos abranger diversos ambientes.

Com o programa já configurado, começaremos a entender os modos do XDebug e como ele pode nos ajudar mesmo se nem soubermos que ele está instalado. Inclusive, recomendamos fazer esse treinamento com algum código seu, de algum projeto já pronto — seja de outro curso da Alura ou um projeto pessoal. Dessa forma, você notará melhor as utilidades do XDebug para você. Nós usaremos exemplos de código bem simples para compreender como o XDebug pode nos ajudar.

Estudaremos o modo de develop, que é como o programa nos ajudará mesmo se não soubermos nada sobre XDebug. Depois, falando sobre perfomance, veremos o modo de profile. Vamos aprender como gerar o perfil de nossa aplicação e analisar onde um problema de performance pode estar.

Na sequência, entraremos efetivamente na parte de debug. No modo de debug, chegaremos em um ponto em que uma requisição web não será completa, porque nossa IDE (ou editor de código, no caso do Visual Studio Code) estará observando nossa execução. Assim, conseguiremos executar linha a linha e, durante esse processo, modificar o valor de uma variável, por exemplo. E, quando continuamos a execução, veremos na resposta da requisição o valor modificado.

Enfim, vamos estudar muitos conteúdos em ambientes diversos (Windows, Linux, Docker). Todos esses conhecimentos te tornarão um desenvolvedor ou uma desenvolvedora mais proficiente na arte de encontrar bugs.

Já falamos bastante sobre o que vamos aprender. Se em qualquer momento desse aprendizado você ficar com alguma dúvida, não hesite em abrir um tópico no fórum. Procuro responder pessoalmente sempre que possível, mas quando não consigo, saiba que temos uma enorme comunidade de alunos, moderadores e instrutores. Com certeza, alguém conseguirá te ajudar.

Agora que vimos um pouco sobre o que aprenderemos nesse treinamento, vamos começar efetivamente a aprender! Te espero no próximo vídeo, para conhecermos o tal do XDebug e o instalarmos em vários ambientes diferentes.

Conhecendo o XDebug - Instalando o XDebug

Olá, pessoal. Bem-vindos de volta.

Antes de utilizarmos o XDebug, precisamos instalá-lo. O XDebug é uma extensão do PHP, vamos deixar um "Para saber mais" para você entender mais a fundo o que é uma extensão do PHP. De forma simplificada: trata-se de um código escrito em linguagem C que podemos acoplar ao PHP. Dessa forma, ele passa a fazer parte do PHP — não é um código externo, ele faz parte do PHP mesmo.

Antes de seguirmos para o passo a passo da instalação no site do XDebug, é importante ressaltar alguns pontos relativos a *versões e compatibilidade entre o PHP e o XDebug.

A versão mais recente do XDebug atualmente é 3.1 ou algo próximo disso. Caso você utilize versões mais antigas do PHP, essa versão do XDebug não funcionará. Por exemplo, se você utiliza uma versão do PHP mais antiga que a 7.2, será preciso usar o XDebug na versão 2.9 ou anterior. Podemos consultar essas informações na página de versões e compatibilidade do site do XDebug.

Entre a versão 2 e a 3 do XDebug existem algumas mudanças. Por exemplo, o conceito de modos que estudaremos nesse treinamento não existia na versão 2 — as configurações eram um pouco misturadas. Além disso, o nome de algumas configurações eram diferentes.

Caso você precise utilizar uma versão antiga do PHP (e, logo, também uma versão antiga do XDebug), saiba que existem essas diferenças. Vale ressaltar que são mudanças pequenas e é possível acompanhar o material com ajuda da documentação do XDebug, pois nesse curso vamos entender os princípios e os conceitos por trás desse programa.

Neste treinamento, usaremos a última versão disponível tanto do PHP quanto do XDebug. No caso, o PHP 8.1 e o XDebug 3.1.

Sabendo de tudo isso, vamos à página de instalação no site do XDebug. Repare que existem várias formas de instalar, porque depende do seu ambiente.

Se você instalou o PHP com um gerenciador de pacotes como o apt, executando o comando sudo apt install php, basta rodar sudo apt install php-xdebug. O XDebug está disponível no mesmo repositório que você instalou o PHP.

Se você utilizou um repositório externo e instalou por um comando semelhante a sudo apt install php8.1, novamente basta adicionar o -xdebug ao final, pois também estará disponível.

Se você está em um ambiente Linux, mas não instalou o PHP através do gerenciador de pacotes, temos o pecl. Este é o instalador de extensões do PHP que vem com a instalação do PHP em ambientes Linux e Mac. Basta rodar pecl xdebug, simples assim. O WSL é um ambiente Linux, então segue esses mesmos conceitos.

Já em ambientes Windows, fora do WSL, esse procedimento é um pouco mais complicado. No caso, temos uma máquina com o PHP na versão 8.1 e, a seguir, vamos descobrir como instalar o XDebug.

Nós poderíamos entrar no site do XDebug, ir até a seção referente ao Windows, abrir a página de downloads e tentar achar a versão correta. Como o meu PHP é 8.1 Non-Thread Safe (NTS), provavelmente seria o PHP 8.1 VS16 (64 bit). Porém, para não correr o risco de selecionar a versão errada, vamos ao wizard de instalação do XDebug (https://xdebug.org/wizard).

Nesta página, temos uma caixa de texto onde podemos colar as informações da nossa instalação do PHP para que o site nos forneça a versão correta. Para obter essas informações, temos duas opções. Podemos ter um arquivo .php que chame a função phpinfo() e abri-lo em algum navegador, a partir de um servidor web. Ou, na linha comando, podemos rodar php -i, que nos informará todas as configurações do PHP.

Vamos optar pela segunda opção. Depois de executar o comando, copiaremos o retorno e colaremos na caixa de texto, no site do XDebug. Em seguida, clicaremos no botão "Analyse my phpinfo() output".

Após a análise do sistema e de outras informações, seremos direcionados para outra página. Sob o tópico "Instructions", teremos o passo a passo de como realizar a instalação. No passo 1, é especificado qual .dll devemos baixar. A seguir, precisamos renomeá-lo para php_xdebug.dll. Por fim, alteraremos o arquivo php.ini, incluindo a linha zend_extension = xdebug.

Então, vamos seguir essas instruções. Primeiro, clicaremos no link disponibilizado no passo 1, para baixar o arquivo .dll. Dentro da nossa instalação do PHP, há uma pasta chamada ext — é nela que vamos salvar este .dll, lembrando de renomeá-lo para php_xdebug.dll.

A seguir, vamos procurar o arquivo php.ini. Quando baixamos o PHP para Windows, esse arquivo não existe. No entanto, temos php.ini-development, que é uma sugestão de configuração para o ambiente de desenvolvimento — é ela que vamos usar. Com o arquivo selecionado, vou pressionar a tecla F2 para renomeá-lo para php.ini. Uma caixa de diálogo será aberta, vamos confirmar que queremos alterar a extensão.

Vamos abrir o php.ini com o Bloco de Notas, pois é um arquivo de texto. No final dele, vamos acrescentar a linha zend_extension = xdebug — poderia ser em qualquer lugar do arquivo. Com essa linha, o PHP procurará por uma extensão chamada xdebug.

Essa extensão precisaria estar na pasta C:\php\ext, onde o PHP fará a busca. Nós fizemos o download em outro diretório, então para evitar um problema vamos pressionar "Ctrl + F" no php.ini e buscar por extension_dir. Veremos o seguinte trecho:

; Directory in which the loadable extensions (modules) reside.
; https://php.net/extension-dir
;extension_dir = "./"
; On windows:
;extension_dir = "ext"

Na última linha deste trecho, é determinado que no Windows seja usada a configuração extension_dir = "ext". Vamos remover o ponto e vírgula no início dessa linha e salvar o arquivo. Teoricamente, nossa instalação está pronta.

Vamos ao terminal. Para melhorar a visualização, vamos rodar cls para limpar a linha de comando. Em seguida, rodando php -v, é possível ver a versão do PHP e a versão do XDebug instalada. Ou seja, o XDebug está pronto para ser utilizado!

Caso você utilize Docker, para ter o XDebug instalado no seu Dockerfile, basta rodar RUN pecl install xdebug && docker-php-ext-enable xdebug.

Em vez de achar o arquivo de configuração e adicionar a linha extension_dir = "ext" para habilitar a extensão, o Docker fornece o comando docker-php-ext-enable xdebug. Em resumo, RUN pecl install xdebug faz a instalação e docker-php-ext-enable xdebug habilita a extensão.

No ambiente Linux, se você realizou a instalação a partir de sudo apt install php-xdebug, um novo arquivo de configuração foi criado automaticamente, com a linha extension_dir = "ext" inclusa. Portanto, o XDebug já estará habilitado.

Porém, se você rodou o pecl install xdebug, talvez precise adicionar manualmente a linha extension_dir = "ext"no arquivo php.ini. Tudo depende do seu ambiente, da forma que a instalação foi feita, entre outros fatores. Então, ao final da instalação, execute o php -v. Caso o retorno não mostre a versão do XDebug, abra o php.ini e adicione a linha extension_dir = "ext".

Assim, falamos sobre vários ambientes. Em geral, a instalação é bem simples. No Windows, é um processo um pouco mais complicado. No WSL, é tão simples quanto no Linux. E, no Docker, basta uma única linha.

Com o XDebug instalado, na sequência começaremos a entender quais vantagens esse programa pode nos proporcionar. No próximo vídeo, já veremos a primeira delas!

Conhecendo o XDebug - Conhecendo o var_dump

Oi, pessoal. Bem-vindos de volta! Antes de mostrar a primeira vantagem do XDebug, vamos ver uma dica para quem usa Docker.

Já falamos do nosso Dockerfile, em que temos o XDebug instalado e habilitado. Mas existem diversas formas de utilizar esse contêiner. Você pode, por exemplo, ter um Docker Compose e configurar todos os seus volumes. Neste treinamento vamos fazer do modo mais rudimentar possível, rodando um único comando: docker run --rm -itv $(pwd):/app -w /app -v $(pwd)/99-xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini -p 8123:8123 php-xdebug bash.

Com este comando, estamos rodando um contêiner do Docker. Assim que o encerrarmos, ele será removido (--rm). Além disso, ele estará no modo interativo, para conseguirmos interagir com o terminal. Criaremos um volume da pasta atual para a pasta app do contêiner e o abriremos. Depois, mandaremos o arquivo 99-xdebug.ini através de um volume para a pasta /usr/local/etc/php/conf.d e o nome do arquivo. Logo comentaremos sobre o 99-xdebug.ini, trata-se de um arquivo de configuração (como o php.ini), ainda vazio. Em seguida, vamos expor uma porta do contêiner (dei o nome php-xdebug para a imagem que criei a partir do Dockerfile) e entraremos nele, com o comando bash.

Executando esse comando, entramos no contêiner que possui o PHP XDebug instalado. Podemos rodar o php -v para nos certificar disso — no retorno, temos a versão do XDebug. Esta era a dica para quem usa o Docker.

Agora, vamos seguir para o 99-xdebug.ini. Ele é um arquivo que criei e ainda está vazio. Como ele está na pasta de arquivos .ini do PHP, ele será lido como se fosse um php.ini também, ou seja, conseguimos adicionar configurações nele. Então, para quem estiver em uma instalação local, tudo que eu codar neste arquivo 99-xdebug.ini, faça no seu arquivo php.ini.

Para achar o arquivo php.ini, podemos rodar php --ini no terminal. O retorno mostrará todos os arquivos de configuração. No meu caso, no Docker, não tenho o php.ini, apenas arquivos extras: o 99-xdebug.ini que acabei de criar e outros dois que o próprio Docker criou para mim (docker-php-ext-sodium.ini e docker-php-ext-xdebug.ini). Inclusive, este segundo foi gerado por causa do comando docker-php-ext-enable xdebug que rodamos anteriormente. O comando criou um arquivo extra e adicionou o zend_extension como fizemos no php.ini, no vídeo passado.

Então, é hora de começar a manipular este arquivo de configurações.

De início, não vamos nos aprofundar no significado desse código. Na primeira linha, vamos digitar xdebug.mode=off. Basicamente, estamos desabilitando o XDebug. Mas ele continua instalado! Podemos executar o php -v para nos certificar.

A seguir, nesta mesma pasta, vamos criar um arquivo teste.php. Nele, declararemos uma variável com a string 'teste' e faremos um var_dump() dessa variável:

$variavel = 'teste';
var_dump();

Podemos rodar este arquivo direto na linha de comando, com php teste.php.

Outra opção é inicializar um servidor web do PHP. Para tanto, executaremos php -S 0.0.0.0:8123 — no caso, 8123 é a porta do contêiner que expus anteriormente. Se você estiver em um ambiente local, você pode rodar php -S localhost:8123 ou na porta de sua escolha.

No navegador, vamos acessar localhost:8123/teste.php. Nesta página, veremos o resultado de var_dump(). Essa função nos mostra informações de algum valor estático, de alguma variável, de algum retorno de uma função. Em nosso cenário, temos string(5)"teste". Ou seja, além do conteúdo da variável, sabemos o seu tipo e, no caso de strings, o seu tamanho.

Voltando ao arquivo teste.ini, vamos mudar de string para um número inteiro:

$variavel = 1;
var_dump($variavel);

Atualizando a página do navegador, o var_dump() mostra se tratar de um inteiro de valor 1. Também podemos atribuir à variável um número muito grande que não cabe num tipo inteiro:

$variavel = 115315414564348631405346546543421654125;
var_dump($variavel);

No navegador, o var_dump() indicará que a variável é do tipo float. Inclusive, será usada a notação científica para diminuir o espaço utilizado: float(1.1531541456434864E+38).

Dessa forma, o var_dump() é uma função que nos traz informações sobre certo valor. Ela é muito usada para fazer depurações, para entendermos o que está acontecendo em determinada parte do código etc. Quando instalamos o XDebug, já temos uma ajuda do var_dump()!

A seguir, vamos ao arquivo 99-xdebug.ini (ou php.ini, dependendo do seu ambiente) e removeremos a linha xdebug.mode=off, que desabilita o XDebug. Se atualizarmos o navegador agora, notaremos que nada mudou, porque todas as configurações do php.ini são lidas na hora em que executamos o PHP. Em outras palavras, nosso PHP ainda está executando, desde quando abrimos o servidor web.

Portanto, encerraremos o servidor, pressionando "Ctrl + C" no terminal. Em seguida, vamos subi-lo de novo. Agora, se atualizarmos o navegador, repararemos que o formato mudou. Temos /app/teste.php:4:float 1.1531541456435E+38, em que 1.1531541456435E+38 está laranja.

Quando instalamos o XDebug, ele modifica a função var_dump() por padrão, para deixá-la com essa coloração diferenciada e adicionar mais informações. Por exemplo, em /app/teste.php:4:float 1.1531541456435E+38, sabemos em que pasta, em que arquivo e em que linha está o var_dump(). Além disso, temos o valor da variável em laranja para facilitar a visualização.

Essa organização é essencial para quando temos vários arquivos e vários var_dump() sendo exibidos, para analisarmos onde cada valor está sendo exposto. Dessa forma, conseguimos fazer a depuração mais facilmente.

O ideal é que, nesse cenário com muitos arquivos e muitos var_dump(), nós paremos de usar essa função e utilizemos o XDebug de outra forma (que estudaremos mais adiante neste curso). Mas vale lembrar que a simples instalação do XDebug já traz essa vantagem.

Por fim, vamos interromper o servidor web. Em seguida, executaremos php teste.php para ver o resultado no próprio terminal. Repare que no retorno temos a pasta, o arquivo e a linha, porém o valor não está colorido como vimos no navegador.

Para mudar esse estilo, podemos habilitar uma configuração. No php.ini, vamos digitar xdebug.cli_color=1. Por padrão, essa configuração é 0, ou seja, ela fica desativada. Rodando o php teste.php novamente, agora temos o valor em laranja também.

Em ambientes Windows, fora do WSL, essa alteração pode não funcionar, porque é preciso de algumas outras instalações. Você pode pesquisar mais sobre isso, se for do seu interesse. Uma opção que pode funcionar é alterar para xdebug.cli_color=2 — a desvantagem é que alguns caracteres podem ficar estranhos. Como estou num ambiente Linux, vou manter como 1.

Desse modo, nesta aula começamos a perceber as vantagens de usar o XDebug, ele está longe de ser uma extensão inútil! De início, sem sabermos absolutamente nada sobre o programa, o var_dump() já foi modificado e melhorado. Mas esta é apenas uma das vantagens do XDebug.

Neste treinamento, conhecemos várias outras vantagens e como utilizar o XDebug. Mas antes mesmo de precisarmos, mostraremos algumas configurações que serão necessárias no nosso ambiente de desenvolvimento — seja usando o PhpStorm (como o meu caso) ou algum outro editor, como o Visual Studio Code.

No próximo vídeo, deixaremos essas configurações prontas!

Sobre o curso XDebug: ferramenta de debug e profiling

O curso XDebug: ferramenta de debug e profiling possui 123 minutos de vídeos, em um total de 39 atividades. Gostou? Conheça nossos outros cursos de PHP em Programação, ou leia nossos artigos de Programação.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Primeiros passos
• Modo develop
• Modo profile
• Modo debug
• Step debugging