Você já enfrentou um momento em que sua aplicação não roda e você precisa entender os passos que levaram à falha? O Xdebug é a ferramenta perfeita para isso, mas depurar uma aplicação PHP dentro de WebAssembly era um desafio até uma das atualizações mais recentes do WordPress Playground.
O WordPress Playground agora suporta Xdebug. Você pode conectar as IDEs Visual Studio Code e PhpStorm para depurar código PHP com pontos de interrupção (breakpoints), execução passo a passo e inspeção de variáveis. Este recurso experimental precisa do seu feedback.
O que você pode fazer com o Xdebug?
Conecte o Xdebug no Playground à sua IDE para:
- Definir breakpoints — Pausar a execução em linhas específicas
- Percorrer o código — Mover-se linha por linha durante a execução
- Inspecionar variáveis — Ver valores durante a execução
- Avaliar expressões — Testar código no contexto atual
Começando com o Xdebug
Vamos depurar um plugin simples usando a Playground CLI e o Xdebug para demonstrar este recurso. Mas não se preocupe, este recurso também está disponível para a PHP-WASM CLI.
Pré-requisitos
Você precisa de:
- Node.js 23 ou superior e npm instalado
- @wp-playground/cli versão 3.0.20 ou superior
- Visual Studio Code com a extensão PHP Debug instalada ou a extensão Xdebug configurada no PhpStorm.
Passos de Configuração
1. Prepare seu código para teste
Para esta demonstração, usarei o seguinte código. Ele exibe uma mensagem no Painel Administrativo do WordPress. Para ver este código em ação, você deve acessar o endereço /wp-admin/:
<?php
}
add_action('admin_notices', 'sam_display_admin_message');
2. Configure sua IDE para escutar o Xdebug
A CLI do WordPress Playground possui uma flag que pode ajudar os desenvolvedores caso não tenham o Xdebug configurado: --experimental-unsafe-ide-integration=, que atualmente suporta duas IDEs: vscode e phpstorm.
Isso economizará tempo gerando os arquivos necessários para iniciar sua depuração.
Visual Studio Code
Para iniciar a depuração, o VS Code precisa do arquivo .vscode/launch.json. Aqui está um exemplo:
{
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003
}
]
}
Inicie o depurador com F5 ou “Run > Start Debugging”. Execute o plugin com a Playground CLI para ver a execução parar quando o código atingir um breakpoint.
Para depurar o plugin acima, podemos inicializar o plugin na Playground CLI com o seguinte comando:
npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mountPhpStorm
Configure o PhpStorm com mapeamentos de caminho (path mappings) e uma configuração de PHP Remote Debug.
- Crie uma configuração de PHP Remote Debug.
- Clique em Start Listening for PHP Debug Connections.
- Execute o plugin com a Playground CLI.
Para executar o plugin com a Playground CLI, execute o comando no terminal:
npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=phpstorm --auto-mountVeja a documentação do Xdebug no PhpStorm para instruções detalhadas de configuração.
Executando Xdebug com PHP-WASM CLI
Outra opção é usar o Xdebug com a PHP-WASM CLI, o que é útil quando você deseja depurar apenas PHP sem um ambiente WordPress.
Para executá-lo, você precisará configurar o Xdebug em seu ambiente de desenvolvimento. Assim que estiver pronto, adicione os breakpoints ao seu arquivo PHP e execute o comando apontando para o arquivo que você gostaria de depurar. Por exemplo, o arquivo abaixo está localizado em src/test.php:
<?php
$test = 42; // Set a breakpoint on this line
echo "Output!n";
function test( $output ) {
echo "Hello Xdebug World!n" . $output . "n";
}
test($test);
No terminal, você executa o comando:
npx @php-wasm/cli@latest --xdebug php/test.phpO resultado será o início do modo de depuração na IDE.
Um esforço da equipe do WordPress Playground para resolver um problema complexo
Trazer o Xdebug para o WebAssembly exigiu resolver desafios técnicos. A equipe do Playground passou meses transformando uma tracking issue de maio de 2023 em código funcional.
Conquista Técnica
A equipe do WordPress Playground fez grandes avanços na integração do Xdebug para depuração no navegador. Esse esforço envolveu inúmeros pull requests que abordaram uma série de desafios técnicos:
- Asyncify Extension: Adicionado suporte ao Xdebug via builds de extensão compartilhada e loaders específicos para asyncify.
- IDE Integration Enhancements: Introduzido mapeamentos de caminho de IDE experimentais para depuração contínua entre o sistema de arquivos virtual (VFS) do Playground e as IDEs do host.
- Xdebug Bridge: Habilitada a ponte (bridge) para ler arquivos diretamente do VFS, alinhando breakpoints e arquivos fonte para experiências de depuração consistentes.
- CLI UX Improvements: Refinada a experiência da CLI para evitar que breakpoints interrompam o processo de inicialização do Playground desnecessariamente.
- DevTools & Debugger Enhancements: Arquivos pré-carregados para melhor depuração no DevTools (#2527), adicionado destaque de sintaxe (#2566), e aprimoradas as inspeções de arrays e manuseio do protocolo Xdebug (#2409).
- Upgraded Toolchain (#2910): Atualizado o Emscripten para resolver problemas de linker, garantindo o carregamento dinâmico suave de extensões compartilhadas como o Xdebug.
Juntos, esses aprimoramentos permitiram fluxos de trabalho robustos de depuração passo a passo, unindo o ambiente WASM do Playground com as capacidades modernas das IDEs. Além disso, trabalhos de base anteriores (#673, #831) sobre carregamento dinâmico estabeleceram a fundação para esses avanços.
O resultado? O Xdebug no WordPress Playground não é apenas funcional; ele fortalece ainda mais o desenvolvimento e testes inteiramente no navegador com a integração com o Chrome Devtools.
O que vem a seguir
A equipe continua trabalhando para trazer o suporte ao Xdebug para mais builds do Playground e explorar a depuração diretamente dentro das ferramentas de desenvolvedor do navegador.
Experimente o Xdebug hoje e compartilhe seu feedback criando uma issue no repositório do Playground ou acesse o canal do #playground no Slack do WordPress. Confira a documentação do Xdebug para mais instruções de configuração, guias de integração com IDE e dicas de solução de problemas.
Créditos para @zieladam e @yannickdecat
Post original: https://make.wordpress.org/playground/2025/11/24/debugging-with-xdebug-is-now-available-in-wordpress-playground/
Fonte: Wordpress Brasil