Pular para o conteúdo principal

Primeiros Passos com Xdebug

Este guia mostra como habilitar o Xdebug no WordPress Playground e começar a depurar seu código.

PHP WASM CLI vs Playground CLI​

Primeiramente, o Xdebug está presente em dois CLI diferentes:

  • @php-wasm/cli: Execute scripts PHP independentes. Use isso quando estiver depurando código PHP, sem precisar de um ambiente WordPress.
  • @wp-playground/cli: Execute uma instalação completa do WordPress. Útil para depurar plugins WordPress, temas ou funcionalidades do núcleo.

Para este guia, vamos utilizar o @wp-playground/cli. Se você não estiver familiarizado com a ferramenta, recomendamos ler o guia do @wp-playground/cli, mas o mesmo processo também pode ser aplicado à depuração de aplicações PHP com o @php-wasm/cli.

Início rápido com npx​

A forma mais rápida de começar é usando npx, que não requer instalação:

npx @wp-playground/cli@latest server --xdebug

Isso inicia o WordPress em http://127.0.0.1:9400 com Xdebug habilitado. Agora você conecta um depurador.

Iniciando com DevTools​

Para depurar com Chrome DevTools, adicione a flag --experimental-devtools:

npx @wp-playground/cli@latest server --xdebug --experimental-devtools

O terminal exibirá uma URL para conectar o Chrome DevTools:

Starting a PHP server...
Setting up WordPress latest
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.3.zip
Fetching SQLite integration plugin...
Booting WordPress...
WordPress is running on http://127.0.0.1:9400 with 1 worker(s)
Starting XDebug Bridge...
Connect Chrome DevTools to CDP at:
devtools://devtools/bundled/inspector.html?ws=localhost:9229

Chrome connected! Initializing Xdebug receiver...
XDebug receiver running on port 9003
Running a PHP script with Xdebug enabled...

Clicando na URL fornecida, por exemplo, devtools://devtools/bundled/inspector.html?ws=localhost:9229, você pode acessar o DevTools conectado à sua aplicação, com a possibilidade de inspecionar todos os arquivos de uma instância WordPress.

Chrome Devtools integrated with Xdebug

Para um exemplo mais prático, vamos debugar um plugin que possui o seguinte código:

<?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');

Na pasta onde o plugin está localizado, vamos executar o comando em nosso terminal:

npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount

O Playground CLI (@wp-playground/cli) detectará automaticamente a pasta do plugin e a montará. Abrindo o projeto em seu navegador e DevTools, você poderá adicionar breakpoints no código do seu plugin e testá-lo linha por linha.

Chrome Devtools integrated with Xdebug

Iniciando com integração IDE​

Similar ao processo com DevTools, vamos utilizar o mesmo código do plugin anterior para depurar com VSCode, adicione a flag --experimental-unsafe-ide-integration=vscode. Esta flag otimizará o processo de configuração para VSCode. Se você trabalha com PhpStorm, apenas adicione a flag --experimental-unsafe-ide-integration=phpstorm.

Para depurar no VSCode você precisará dos seguintes pré-requisitos:

  1. Uma extensão para adicionar suporte a PHP profiling, por exemplo, PHP Profiler
  2. Uma pasta .vscode/. Se o arquivo launch.json não existir, não se preocupe, o @wp-playground/cli o criará.
  3. Habilite os pontos de interrupção (breakpoints) em seu IDE. Alguns IDEs vêm com este recurso desativado, então preste atenção a este detalhe.

Se tudo estiver pronto, execute o comando:

npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount

Agora, vá para o seu código, adicione os breakpoints e bons testes.

Xdebug em execução no VSCode

Esta funcionalidade está em modo experimental. Até que seja concluída, precisaremos do seu feedback. Por favor, conecte-se conosco no canal Slack #playground e compartilhe seus pensamentos.