Depuração com Xdebug agora está disponível no WordPress Playground

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
/**
 * Plugin Name: Simple Admin Message
 * Description: Displays a simple message in the WordPress admin
 * Version: 1.0
 * Author: Playground Team
 */

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

// Display admin notice
function sam_display_admin_message() {
    $message = 'Hello! This is a simple admin message.';
    ?>
    <div class="notice notice-info is-dismissible">
        <p><?php _e($message, 'simple-admin-message'); ?></p>
    </div>
    <?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-mount

PhpStorm

Configure o PhpStorm com mapeamentos de caminho (path mappings) e uma configuração de PHP Remote Debug.

1. Crie uma configuração de PHP Remote Debug.
2. Clique em Start Listening for PHP Debug Connections.
3. 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-mount

Veja 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.php

O 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/