[Docs] Add xdebug testing page

packages/docs/site/docs/developers/07-xdebug/01-introduction.md

@@ -0,0 +1,40 @@
+---
+title: Using Xdebug with PHP WASM - Introduction
+slug: /developers/xdebug/introduction
+description: Debug PHP code running in WebAssembly within WordPress Playground using Xdebug, Chrome DevTools, and IDE integration.
+---
+
+# Using Xdebug with PHP WASM
+
+Xdebug is a debugging extension for PHP that lets you set breakpoints, inspect variables, and step through your code. WordPress Playground includes Xdebug in its WebAssembly-compiled PHP, so you can debug WordPress code running directly in your browser or IDE.
+
+## Why Xdebug matters for PHP WASM
+
+Debugging PHP code in WebAssembly is different from debugging traditional PHP. Without Xdebug, you're limited to `var_dump()` and `error_log()` statements. Xdebug gives you a proper debugger with breakpoints, variable inspection, and call stack navigation—the same tools you'd use when debugging PHP on a regular server.
+
+## XDebug on WordPress Playground
+
+For a quick start, check the [getting started with Xdebug guide](/developers/xdebug/getting-started)
+
+You'll learn to debug:
+
+-   Form processing logic
+-   Input validation
+-   WordPress hooks and filters
+
+## Two debugging approaches
+
+WordPress Playground supports two ways to debug with Xdebug:
+
+**Chrome DevTools**: Debug directly in your browser without any IDE setup. Great for quick debugging sessions or when you want to see everything in one place.
+
+**IDE integration**: Use VSCode or PhpStorm with full IDE features, including code navigation, project-wide search, and advanced breakpoint conditions. Better for complex debugging scenarios.
+
+## What you'll need
+
+-   Node.js installed
+-   Chrome or Chromium browser (for DevTools debugging)
+-   Visual Studio Code or PhpStorm (for IDE debugging, optional)
+-   Basic familiarity with WordPress plugin development
+
+**Next**: [Getting Started with Xdebug →](/developers/xdebug/getting-started)

packages/docs/site/docs/developers/07-xdebug/02-getting-started.md

@@ -0,0 +1,126 @@
+---
+title: Getting Started with Xdebug
+slug: /developers/xdebug/getting-started
+description: Before you can start debugging, you need to run WordPress Playground with Xdebug enabled. This guide covers the basics.
+---
+
+# Getting Started with Xdebug
+
+This guide shows you how to enable Xdebug in WordPress Playground and start debugging your code.
+
+## PHP WASM CLI vs Playground CLI
+
+First, Xdebug is present in two different CLIs:
+
+-   **`@php-wasm/cli`**: Run standalone PHP scripts. Use this when debugging PHP code without needing a WordPress environment.
+-   **`@wp-playground/cli`**: Run a full WordPress installation. Useful for debugging WordPress plugins, themes, or core functionality.
+
+For this guide, we'll use `@wp-playground/cli`. Suppose you're not familiar with the tool. In that case, we recommend reading the [`@wp-playground/cli` guide](/developers/local-development/wp-playground-cli), but the same process can also be applied to debugging PHP applications with `@php-wasm/cli`.
+
+## Quick start with `npx`
+
+The fastest way to get started is using npx, which doesn't require installation:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug
+```
+
+This starts WordPress on `http://127.0.0.1:9400` with Xdebug enabled. Now you connect a debugger.
+
+:::info
+Only one project can be debugged at a time.
+:::
+
+## Starting with DevTools
+
+To debug with Chrome DevTools, add the `--experimental-devtools` flag:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-devtools
+```
+
+The terminal will display a URL to connect to Chrome DevTools:
+
+```bash
+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...
+```
+
+By clicking on the provided URL, for example, `devtools://devtools/bundled/inspector.html?ws=localhost:9229`, you can access DevTools connected to your application, with the ability to inspect all files of a WordPress instance.
+
+![Chrome Devtools integrated with Xdebug](@site/static/img/developers/xdebug/playground-xdebug-on-devtools.webp)
+
+For a more practical example, let's debug a plugin that has the following code:
+
+```PHP
+<?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');
+```
+
+In the folder where the plugin is located, let's run the command in our terminal:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount
+```
+
+The Playground CLI(`@wp-playground/cli`) will automatically detect the plugin folder and mount it. Opening the project in your browser and DevTools, you'll be able to add breakpoints in your plugin's code and test it line by line.
+
+![Chrome Devtools integrated with Xdebug](@site/static/img/developers/xdebug/playground-cli-running-xdebug-on-devtools.webp)
+
+## Starting with IDE integration
+
+Similar to the process with DevTools, let's use the same plugin code from before to debug with VS Code, and add the `--experimental-unsafe-ide-integration=vscode` flag. This flag will optimize the setup process for VS Code. If you're working with PhpStorm, just add the `--experimental-unsafe-ide-integration=phpstorm` flag.
+
+:::info
+This flag is marked as `unsafe` because it edits the IDE config files to set Xdebug path mappings and web server details. **CAUTION:** If there are bugs, this feature may cause your IDE configuration files to break. Please consider backing up your IDE configs before using this feature.
+:::
+
+To debug in VS Code, you'll need the following prerequisites:
+
+1. An extension to add PHP profiling support, for example, [PHP Profiler](https://open-vsx.org/extension/devsense/profiler-php-vscode)
+2. Have a `.vscode/` folder for VS Code and `.idea` for PhpStorm.
+3. Enable breakpoints in your IDE. Some IDEs come with this feature disabled, so be aware of this detail.
+
+If everything is ready, you run the command:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount
+```
+
+Now, go to your code, add the breakpoints, and happy testing.
+
+![Xdebug in action on VS Code](@site/static/img/developers/xdebug/xdebug-in-action-on-vscode.webp)
+
+This feature is in experimental mode. Until it's finished, we'll need your feedback. Please connect with us in the [#playground Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K) and share your thoughts.

packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/developers/07-xdebug/01-introduction.md

@@ -0,0 +1,42 @@
+---
+title: Usando Xdebug con PHP WASM - Introducción
+slug: /developers/xdebug/introduction
+description: Depura código PHP ejecutándose en WebAssembly dentro de WordPress Playground usando Xdebug, Chrome DevTools e integración con IDE.
+---
+
+# Usando Xdebug con PHP WASM
+
+Xdebug es una extensión de depuración para PHP que te permite establecer puntos de interrupción, inspeccionar variables y recorrer tu código paso a paso. WordPress Playground incluye Xdebug en su PHP compilado para WebAssembly, por lo que puedes depurar código de WordPress que se ejecuta directamente en tu navegador o IDE.
+
+## Por qué Xdebug es importante para PHP WASM
+
+Depurar código PHP en WebAssembly es diferente de depurar PHP tradicional. Sin Xdebug, estás limitado a declaraciones `var_dump()` y `error_log()`. Xdebug te ofrece un depurador adecuado con puntos de interrupción, inspección de variables y navegación de la pila de llamadas: las mismas herramientas que usarías al depurar PHP en un servidor regular.
+
+## XDebug en WordPress Playground
+
+Para un inicio rápido, consulta la [guía de primeros pasos con Xdebug](/developers/xdebug/getting-started)
+
+Aprenderás a depurar:
+
+-   Lógica de procesamiento de formularios
+-   Validación de entrada
+-   Hooks y filtros de WordPress
+
+## Dos enfoques de depuración
+
+WordPress Playground admite dos formas de depurar con Xdebug:
+
+**Chrome DevTools**: Depura directamente en tu navegador sin configuración de IDE. Excelente para sesiones rápidas de depuración o cuando quieres ver todo en un solo lugar.
+
+**Integración con IDE**: Usa VSCode o PhpStorm con funciones completas de IDE como navegación de código, búsqueda en todo el proyecto y condiciones avanzadas de puntos de interrupción. Mejor para escenarios de depuración complejos.
+
+Ambos métodos funcionan con la misma configuración de Xdebug. Incluso puedes usarlos simultáneamente. Elige lo que mejor se adapte a tu flujo de trabajo.
+
+## Lo que necesitarás
+
+-   Node.js instalado
+-   Navegador Chrome o Chromium (para depuración con DevTools)
+-   Visual Studio Code o PhpStorm (para depuración con IDE, opcional)
+-   Conocimiento básico de desarrollo de plugins de WordPress
+
+**Siguiente**: [Primeros Pasos con Xdebug →](/developers/xdebug/getting-started)

packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/developers/07-xdebug/02-getting-started.md

@@ -0,0 +1,160 @@
+---
+title: Primeros Pasos con Xdebug
+slug: /developers/xdebug/getting-started
+description: Antes de comenzar a depurar, necesitas ejecutar WordPress Playground con Xdebug habilitado. Esta guía cubre lo básico.
+---
+
+<!-- # Getting Started with Xdebug -->
+
+# Primeros Pasos con Xdebug
+
+<!-- This guide shows you how to enable Xdebug in WordPress Playground and start debugging your code. -->
+
+Esta guía te muestra cómo habilitar Xdebug en WordPress Playground y comenzar a depurar tu código.
+
+<!-- ## PHP WASM CLI vs Playground CLI -->
+
+## PHP WASM CLI vs Playground CLI
+
+<!-- First, Xdebug is present in two different CLIs: -->
+
+Primero, Xdebug está presente en dos CLI diferentes:
+
+-   **`@php-wasm/cli`**: Ejecuta scripts PHP independientes. Úsalo cuando estés depurando código PHP sin necesidad de un entorno WordPress.
+-   **`@wp-playground/cli`**: Ejecuta una instalación completa de WordPress. Útil para depurar plugins de WordPress, temas o funcionalidades del núcleo.
+
+<!-- For this guide, we'll use `@wp-playground/cli`. If you're not familiar with the tool, we recommend reading the [`@wp-playground/cli` guide](/developers/local-development/wp-playground-cli), but the same process can also be applied to debugging PHP applications with `@php-wasm/cli`. -->
+
+Para esta guía, utilizaremos `@wp-playground/cli`. Si no estás familiarizado con la herramienta, recomendamos leer la guía de [`@wp-playground/cli`](/developers/local-development/wp-playground-cli), pero el mismo proceso también puede aplicarse a la depuración de aplicaciones PHP con `@php-wasm/cli`.
+
+<!-- ## Quick start with `npx` -->
+
+## Inicio rápido con `npx`
+
+<!-- The fastest way to get started is using npx, which doesn't require installation: -->
+
+La forma más rápida de comenzar es usar npx, que no requiere instalación:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug
+```
+
+<!-- This starts WordPress on `http://127.0.0.1:9400` with Xdebug enabled. Now you connect a debugger. -->
+
+Esto inicia WordPress en `http://127.0.0.1:9400` con Xdebug habilitado. Ahora conectas un depurador.
+
+<!-- ## Starting with DevTools -->
+
+## Iniciando con DevTools
+
+<!-- To debug with Chrome DevTools, add the `--experimental-devtools` flag: -->
+
+Para depurar con Chrome DevTools, agrega la bandera `--experimental-devtools`:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-devtools
+```
+
+<!-- The terminal will display a URL to connect Chrome DevTools: -->
+
+La terminal mostrará una URL para conectar Chrome DevTools:
+
+```bash
+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...
+```
+
+<!-- By clicking on the provided URL, for example, `devtools://devtools/bundled/inspector.html?ws=localhost:9229`, you can access DevTools connected to your application, with the ability to inspect all files of a WordPress instance. -->
+
+Al hacer clic en la URL proporcionada, por ejemplo, `devtools://devtools/bundled/inspector.html?ws=localhost:9229`, puedes acceder a DevTools conectado con tu aplicación, con la posibilidad de inspeccionar todos los archivos de una instancia WordPress.
+
+![Chrome Devtools integrated with Xdebug](@site/static/img/developers/xdebug/playground-xdebug-on-devtools.webp)
+
+<!-- For a more practical example, let's debug a plugin that has the following code: -->
+
+Para un ejemplo más práctico, vamos a depurar un plugin que tiene el siguiente código:
+
+```PHP
+<?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');
+```
+
+<!-- In the folder where the plugin is located, let's run the command in our terminal: -->
+
+En la carpeta donde se encuentra el plugin, ejecutemos el comando en nuestro terminal:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-devtools --auto-mount
+```
+
+<!-- The Playground CLI(`@wp-playground/cli`) will automatically detect the plugin folder and mount it. Opening the project in your browser and DevTools, you'll be able to add breakpoints in your plugin's code and test it line by line. -->
+
+El Playground CLI (`@wp-playground/cli`) detectará automáticamente la carpeta del plugin y la montará. Abriendo el proyecto en tu navegador y DevTools, podrás agregar breakpoints en el código de tu plugin y probarlo línea por línea.
+
+![Chrome Devtools integrated with Xdebug](@site/static/img/developers/xdebug/playground-cli-running-xdebug-on-devtools.webp)
+
+<!-- ## Starting with IDE integration -->
+
+## Iniciando con integración IDE
+
+<!-- Similar to the process with DevTools, let's use the same plugin code from before to debug with VSCode, add the `--experimental-unsafe-ide-integration=vscode` flag. This flag will optimize the setup process for VSCode. If you're working with PhpStorm, just add the `--experimental-unsafe-ide-integration=phpstorm` flag. -->
+
+Similar al proceso con DevTools, vamos a utilizar el mismo código del plugin anterior para depurar con VSCode, agrega la bandera `--experimental-unsafe-ide-integration=vscode`. Esta bandera optimizará el proceso de configuración para VSCode. Si trabajas con PhpStorm, simplemente agrega la bandera `--experimental-unsafe-ide-integration=phpstorm`.
+
+<!-- To debug in VSCode you'll need the following prerequisites: -->
+
+Para depurar en VSCode necesitarás los siguientes prerrequisitos:
+
+1. Una extensión para agregar soporte de PHP profiling, por ejemplo, [PHP Profiler](https://open-vsx.org/extension/devsense/profiler-php-vscode)
+2. Una carpeta `.vscode/`. Si el archivo `launch.json` no existe, no te preocupes, `@wp-playground/cli` lo creará.
+3. Habilita los puntos de interrupción (breakpoints) en tu IDE. Algunos IDEs vienen con esta característica desactivada, así que presta atención a este detalle.
+
+<!-- If everything is ready, you run the command: -->
+
+Si todo está listo, ejecuta el comando:
+
+```bash
+npx @wp-playground/cli@latest server --xdebug --experimental-unsafe-ide-integration=vscode --auto-mount
+```
+
+<!-- Now, go to your code, add the breakpoints and happy testing. -->
+
+Ahora, ve a tu código, agrega los breakpoints y buenas pruebas.
+
+![Xdebug en ejecución en VSCode](@site/static/img/developers/xdebug/xdebug-in-action-on-vscode.webp)
+
+<!-- This feature is in experimental mode. Until it is completed, we will need your feedback. Please connect with us in the [#playground Slack channel](https://wordpress.slack.com/archives/C04EWKGDJ0K) and share your thoughts. -->
+
+Esta característica está en modo experimental. Hasta que se complete, necesitaremos tu retroalimentación. Por favor, conéctate con nosotros en el [canal Slack #playground](https://wordpress.slack.com/archives/C04EWKGDJ0K) y comparte tus pensamientos.