Como Depurar e Fazer Profiling de Aplicações PHP com Xdebug

Sobre nós: Site pessoal de Timofey Bugaevsky e da empresa Zetka Interactive

Guias: Uma colecção abrangente de guias técnicos escritos da perspectiva de um programador sénior. Cada artigo fornece explicações aprofundadas, exemplos de código práticos e padrões prontos para produção.

Backend: Desenvolvimento do lado do servidor com vários frameworks

O Xdebug é a ferramenta essencial para programadores PHP, disponibilizando depuração passo a passo, profiling e capacidades de code coverage. Embora o `var_dump` e o logging tenham o seu lugar, nada s...

O Xdebug é a ferramenta essencial para programadores PHP, disponibilizando depuração passo a passo, profiling e capacidades de code coverage. Embora o var_dump e o logging tenham o seu lugar, nada supera uma depuração adequada para compreender fluxos de código complexos. Este guia aborda a configuração e utilização eficaz do Xdebug, na perspetiva de um programador sénior.

Porque o Xdebug

O Xdebug transforma o desenvolvimento em PHP:

Depuração Passo a Passo: Defina breakpoints, inspecione variáveis, percorra o código passo a passo
Profiling: Encontre estrangulamentos de desempenho com dados de temporização detalhados
Stack Traces: Obtenha rastos de erro significativos com variáveis locais
Code Coverage: Meça a cobertura de testes com precisão
Integração com IDE: Funciona com PhpStorm, VS Code e outros editores

Aviso: Nunca ative o Xdebug em servidores de produção — tem um impacto significativo no desempenho.

Instalação

Instalação Padrão

# A usar o pecl
pecl install xdebug
# No Ubuntu/Debian
sudo apt install php-xdebug
# No CentOS/RHEL
sudo dnf install php-pecl-xdebug

Instalação em Docker

Adicione ao seu Dockerfile de desenvolvimento:

FROM php:8.2-fpm
# Instalar o Xdebug
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug
# Copiar a configuração do Xdebug
COPY xdebug.ini $PHP_INI_DIR/conf.d/xdebug.ini

Crie xdebug.ini:

[xdebug]
zend_extension=xdebug
; Enable step debugging
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
; Optionally enable profiling
; xdebug.mode=debug,profile
; xdebug.output_dir=/var/www/html/profiles

Para Docker Compose, garanta a rede adequada:

version: '3.8'
services:
php:
build:
context: .
dockerfile: Dockerfile.dev
volumes:
- ./:/var/www/html
environment:
- PHP_IDE_CONFIG=serverName=docker
extra_hosts:
- "host.docker.internal:host-gateway"

Modos de Configuração do Xdebug 3

O Xdebug 3 utiliza modos para controlar funcionalidades. Defina através de xdebug.mode:

Mode	Description
`off`	Nada está ativado (predefinição)
`develop`	Ajudas ao desenvolvimento (melhorias no var_dump)
`debug`	Depuração passo a passo
`profile`	Profiling
`coverage`	Code coverage
`trace`	Rasto de funções

Combine modos com vírgulas:

xdebug.mode=debug,profile,coverage

Configuração da Depuração Passo a Passo

Configuração para Depuração

Crie ou edite xdebug.ini:

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=trigger
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
xdebug.log=/tmp/xdebug.log

Métodos de Trigger

Com startwithrequest=trigger, a depuração inicia quando:

Parâmetro GET/POST: ?XDEBUGSESSIONSTART=PHPSTORM
Cookie: XDEBUG_SESSION=PHPSTORM
Extensão do browser: Xdebug Helper para Chrome/Firefox

Configuração do PhpStorm

Vá a Settings → PHP → Debug
Defina a porta de Debug para 9003
Ative «Can accept external connections»
Vá a Settings → PHP → Servers
Adicione um servidor com mapeamentos de caminhos para Docker:

- Name: docker - Host: localhost - Port: 80 - Debugger: Xdebug - Path mappings: /local/path → /var/www/html

Configuração do VS Code

Instale a extensão PHP Debug e, em seguida, crie .vscode/launch.json:

{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
}
},
{
"name": "Launch currently open script",
"type": "php",
"request": "launch",
"program": "${file}",
"cwd": "${fileDirname}",
"port": 9003
}
]
}

Depurar Scripts CLI

Para scripts PHP na linha de comandos:

# Definir variável de ambiente
export XDEBUG_SESSION=1
php artisan my:command
# Ou inline
XDEBUG_SESSION=1 php script.php

Profiling de Desempenho

Ativar Profiling

Configure para profiling a pedido:

[xdebug]
zend_extension=xdebug
xdebug.mode=profile
xdebug.start_with_request=trigger
xdebug.output_dir=/var/www/html/profiles
xdebug.profiler_output_name=cachegrind.out.%p.%t

Acione o profiling adicionando ?XDEBUG_PROFILE a qualquer URL:

http://localhost/api/users?XDEBUG_PROFILE

Analisar Dados de Profiling

Os ficheiros de profiling usam o formato cachegrind. Analise com:

KCachegrind (Linux/macOS):

# Instalar
sudo apt install kcachegrind # Ubuntu
brew install qcachegrind # macOS
# Abrir perfil
kcachegrind profiles/cachegrind.out.12345

Webgrind (baseado na Web):

# Clonar o webgrind
git clone https://github.com/jokkedk/webgrind.git
# Apontar o servidor web para a pasta do webgrind
# Aceder via http://localhost/webgrind

Ler a Saída do Profiler

Métricas-chave a analisar:

Self Time: Tempo gasto na própria função
Inclusive Time: Tempo incluindo as funções chamadas
Call Count: Número de vezes que a função foi chamada

Foque-se em:

Funções com self time elevado (alvos de otimização)
Funções chamadas em excesso (potenciais queries N+1)
Chamadas de funções inesperadas (depuração)

Boas Práticas de Profiling

// Fazer profiling de secções específicas de código
xdebug_start_profiling();
// O seu código aqui
$result = expensiveOperation();
xdebug_stop_profiling();

Code Coverage

Configurar para Coverage

[xdebug]
xdebug.mode=coverage

Integração com PHPUnit

<!--phpunit.xml-->
<phpunit>
<coverage processUncoveredFiles="true">
<include>
<directory suffix=".php">./app</directory>
</include>
<exclude>
<directory>./vendor</directory>
</exclude>
<report>
<html outputDirectory="coverage-report"/>
<text outputFile="coverage.txt"/>
</report>
</coverage>
</phpunit>

Executar com coverage:

php artisan test --coverage
# ou
./vendor/bin/phpunit --coverage-html coverage-report

Ajudas ao Desenvolvimento

var_dump Melhorado

Com xdebug.mode=develop:

$data = ['users' => [
['name' => 'John', 'email' => '[email protected]'],
['name' => 'Jane', 'email' => '[email protected]'],
]];
var_dump($data); // Agora mostra saída colorida e formatada

Stack Traces

O Xdebug melhora automaticamente os stack traces de erro:

function level3() {
throw new Exception("Something went wrong");
}
function level2() {
level3();
}
function level1() {
level2();
}
level1(); // O stack trace mostra todos os níveis com variáveis locais

Resolução de Problemas

Verificar a Instalação

<?php
phpinfo(); // Procure a secção do Xdebug
// ou
php -v // Deverá mostrar «with Xdebug»

Verificar a Configuração

php -i | grep xdebug

Problemas Comuns

Connection refused:

Verifique se o IDE está a escutar na porta correta
Verifique as regras da firewall
Garanta que client_host está correto (use host.docker.internal para Docker)

A depuração não inicia:

Verifique se xdebug.mode inclui debug
Verifique o método de trigger (cookie, parâmetro GET)
Reveja o log do Xdebug: xdebug.log=/tmp/xdebug.log

Problemas de mapeamento de caminhos:

Garanta que a configuração do servidor no IDE corresponde aos caminhos reais
Para Docker, mapeie os caminhos do contentor para os caminhos locais

Impacto no desempenho:

Use startwithrequest=trigger em vez de yes
Desative o Xdebug quando não for necessário
Nunca use em produção

Problemas Específicos do Docker

Se host.docker.internal não funcionar:

# docker-compose.yml
services:
php:
extra_hosts:
- "host.docker.internal:host-gateway"

Ou use diretamente o IP da sua máquina anfitriã em xdebug.client_host.

Configuração Multi-Mode

Para ambientes de desenvolvimento que necessitam de todas as funcionalidades:

[xdebug]
zend_extension=xdebug
; Enable multiple modes
xdebug.mode=debug,develop,coverage
; Debugging settings
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.idekey=PHPSTORM
; Profiling (enable mode when needed)
; xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_output_name=cachegrind.out.%p
; Logging
xdebug.log=/tmp/xdebug.log
xdebug.log_level=3

Principais Conclusões

Use o modo trigger: Não ative a depuração para todos os pedidos
Faça profiling antes de otimizar: Encontre os verdadeiros estrangulamentos, não adivinhe
Configure mapeamentos de caminhos: Essencial para Docker e depuração remota
Nunca use em produção: O impacto no desempenho é significativo
Tire partido das funcionalidades do IDE: Breakpoints, watches e call stacks
Verifique o log: Quando a depuração falha, os logs do Xdebug dizem-lhe porquê

O Xdebug transforma a depuração em PHP de frustrantes instruções de impressão para um fluxo de trabalho de desenvolvimento profissional. Domine-o e resolverá bugs complexos em minutos, em vez de horas.

Os materiais do site podem ser usados com referência à fonte. Licença

Contate-nos

Sobre nós

Guias

Backend

Como Depurar e Fazer Profiling de Aplicações PHP com Xdebug

Свернуть [_]

Log In

Como Depurar e Fazer Profiling de Aplicações PHP com Xdebug

Porque o Xdebug

Instalação

Instalação Padrão

Instalação em Docker

Modos de Configuração do Xdebug 3

Configuração da Depuração Passo a Passo

Configuração para Depuração

Métodos de Trigger

Configuração do PhpStorm

Configuração do VS Code

Depurar Scripts CLI

Profiling de Desempenho

Ativar Profiling

Analisar Dados de Profiling

Ler a Saída do Profiler

Boas Práticas de Profiling

Code Coverage

Configurar para Coverage

Integração com PHPUnit

Ajudas ao Desenvolvimento

var_dump Melhorado

Stack Traces

Resolução de Problemas

Verificar a Instalação

Verificar a Configuração

Problemas Comuns

Problemas Específicos do Docker

Configuração Multi-Mode

Principais Conclusões