miércoles, 11 de junio de 2025

Depurar aplicaciones PHP CLI de Laravel con XDebug y VS Code o Eclipse

La clave está en que el IDE, tanto VS Code como Eclipse, levantan un puerto de escucha al cual XDebug va a invocar cuando tenga un proceso para depurar. Puesto en términos de la arquitectura cliente/servidor, el IDE es el servidor y XDebug es el cliente.

Lo primero es instalar XDebug prestando mucha atención a que sea compatible con la versión de PHP instalada, incluso en el número menor de la versión. Por ejemplo, no sirve si PHP es la versión 8.4 y XDebug es para la versión de PHP 8.3. Una manera de asegurarse de que sean compatibles es instalando ambos módulos de una misma fuente, como por ejemplo en Ubuntu sería el package manager: paquetes php-cli y php-xdebug.

Otra clave es que PHP CLI tiene un servidor integrado. Es decir, desde la línea de comando de PHP se puede iniciar un servidor propio de PHP, que no es ni Apache, ni Nginx, ni nada. Es PHP CLI. Por lo tanto, el siguiente método para depurar aplicaciones PHP CLI también sirve para depurar este servidor integrado. Este servidor es el mismo que se usa al invocar el comando php artisan serve, además de tener otra manera de ser invocado que no depende de Artisan (Laravel).

La versión de Eclipse tiene que ser PDT (PHP Development Tools).

Para conectar Eclipse o VS Code a una sesión de depuración contra php artisan serve, necesitas tres cosas clave:

  1. Xdebug instalado y configurado correctamente en tu PHP.
  2. Una configuración de depuración en Eclipse PDT.
  3. Una configuración de depuración en VS Code.

Vamos paso a paso:

Paso 1: Configurar Xdebug en tu PHP

Xdebug es una extensión de PHP que permite la depuración. Necesitas asegurarte de que esté instalada y configurada para "escuchar" conexiones desde tu IDE.

  1. Verificar la instalación de Xdebug: Abre tu terminal y ejecuta:

    Bash
    php -v

    Deberías ver una línea que menciona Xdebug, por ejemplo: with Xdebug v3.x.x, ... Si no la ves, Xdebug no está instalado o no está habilitado.

  2. Encontrar tu archivo php.ini: Ejecuta en la terminal:

    Bash
    php --ini

    Esto te mostrará la ruta al php.ini que PHP CLI (y por ende php artisan serve) está utilizando. Abre ese archivo con un editor de texto. Es normal que además de un archivo .ini general, haya otros archivos .ini particulares para los diferentes módulos o funciones que tiene PHP. Si es así, php --ini va a mostrar no uno, sino varios .ini. Es imprescindible identificar el que corresponde a la extensión XDebug, para ello se puede uno ayudar con php --ini | grep xdebug. Eso no quita que puede no haber varios .ini sino estar toda la configuración en el .ini general, en tal caso con php --ini basta para verlo. Abrir este archivo en un editor de texto.

  3. Configurar Xdebug en php.ini (para Xdebug 3.x.x): Asegúrate de que las siguientes líneas estén presentes y configuradas así. Si ves ; al principio de una línea, quítalo para descomentarla.


    [XDebug]
zend_extension=xdebug.so           ; O la ruta completa a tu archivo .dll/.so de Xdebug. Ej: C:\php\ext\php_xdebug.dll
xdebug.mode = develop,debug        ; Habilita el modo de desarrollo y depuración
xdebug.start_with_request = yes
xdebug.log = /tmp/xdebug.log       ; (Opcional, pero MUY recomendable para depurar problemas de Xdebug). Pon una ruta donde PHP pueda escribir.

    Importante: Después de modificar php.ini, debes detener/reiniciar php artisan serve para que los cambios tengan efecto.

  4. Hay configuraciones para especificar host y puerto, pero si no se especifica, para XDebug 3 el default es localhost, puerto 9003.

Paso 2: Configurar Eclipse PDT para la Depuración

  1. Abre tu proyecto Laravel en Eclipse.

  2. Ve a Run > Debug Configurations... (Ejecutar > Configuraciones de Depuración...).

  3. Crea una nueva configuración:

    • En el panel izquierdo, haz clic derecho en "PHP Web Application" y selecciona "New Configuration" (Nueva configuración).

  4. Configura la nueva configuración:

    • Name (Nombre): Dale un nombre descriptivo, como "Laravel Artisan Serve Debug".

    • Server (Servidor):

      • Haz clic en "New..." (Nuevo...) para crear un nuevo servidor PHP.
      • Server type: Built-In PHP Server
      • Name (Nombre): "Laravel Artisan Serve"
      • Base URL (URL Base): http://localhost:8000 (o el puerto que php artisan serve esté usando).
      • Document Root (Raíz del Documento): Aquí viene la parte importante. Debes apuntar a la carpeta public de tu proyecto Laravel.
        • Ejemplo: Si tu proyecto Laravel está en C:\Users\TuUsuario\proyectos\mi-laravel-app, el Document Root sería C:\Users\TuUsuario\proyectos\mi-laravel-app\public.
      • Debugger: Selecciona "XDebug".
      • Puerto del Depurador: Asegúrate de que sea 9003 (o el que configuraste en xdebug.client_port en php.ini).
      • Haz clic en "Finish" (Finalizar).

    • File (Archivo):

      • Deja esto como está, ya que la depuración se activará por una solicitud HTTP externa.

    • URL:

      • Auto Generate (Generar automáticamente): Asegúrate de que esta casilla esté marcada. Esto construirá la URL de la página a la que quieres depurar.

    • Haz clic en "Apply" (Aplicar) y luego en "Close" (Cerrar).

Eclipse PDT va a estar escuchando en el puerto configurado apenas guardemos la configuración. La clave es entender que Eclipse no tiene un disyuntor para encender o apagar el depurador; está siempre encendido.

Paso 3: Configurar VS Code

  1. VS Code necesita una extensión para comunicarse con Xdebug.

    1. Abre VS Code.
    2. Ve a la vista de Extensiones (icono de cuadrados en la barra lateral izquierda o Ctrl+Shift+X).
    3. Busca "PHP Debug" y instala la extensión creada por XDebug.org.

Paso 4: Crear la Configuración de Lanzamiento (launch.json) en VS Code

Aquí le dices a VS Code cómo quieres iniciar o adjuntar una sesión de depuración.

  1. Abre tu proyecto Laravel en VS Code.

  2. Ve a la vista de "Ejecutar y Depurar" (Run and Debug) (icono de un bicho con una flecha en la barra lateral izquierda o Ctrl+Shift+D).

  3. Si es la primera vez, verás un texto que dice "crear un archivo launch.json". Haz clic en ese enlace.

  4. VS Code te preguntará qué entorno quieres depurar. Selecciona "PHP".

  5. Esto creará un archivo launch.json dentro de una nueva carpeta .vscode/ en la raíz de tu proyecto. El contenido predeterminado suele ser suficiente, pero vamos a revisarlo y asegurarnos de que la parte de mapeo de rutas es correcta.

    JSON
    {
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003, // Debe coincidir con xdebug.client_port en php.ini
            "stopOnEntry": false, // Opcional: true para que se detenga al inicio de la ejecución
            "pathMappings": {
                // ¡Esto es CRÍTICO para que los breakpoints funcionen!
                // 'ruta_servidor_php_ve': '${workspaceFolder}/ruta_proyecto_local'
                // Generalmente, la raíz de tu proyecto Laravel en el servidor web (o donde Xdebug está "pensando" que está)
                // se mapea a la raíz de tu proyecto en VS Code.
                "/var/www/html/mi-laravel-app": "${workspaceFolder}", // Si tu proyecto está en Docker/VM
                // O si ejecutas directamente en Windows/Linux, puede ser solo la raíz del proyecto.
                // Asegúrate de que esta ruta '/var/www/html/mi-laravel-app' coincide con la ruta real del proyecto en el servidor PHP
                // (el que `php artisan serve` usaría si lo ejecutaras en un entorno de servidor).
                // Para `php artisan serve` en tu máquina local, a menudo es suficiente con:
                "F:/proyectos/mi-laravel-app": "${workspaceFolder}" // Ejemplo en Windows si tu proyecto está ahí
            },
            "ignore": [
                "**/vendor/**/*.php" // Para ignorar archivos dentro de vendor/
            ]
        }
    ]
}

    Punto clave: pathMappings

    • "ruta_del_proyecto_en_el_servidor": Esta es la ruta absoluta donde el código PHP se está ejecutando en el servidor (o el entorno de PHP). Si estás usando Docker, sería la ruta dentro del contenedor (ej. /var/www/html/tu-proyecto). Si estás ejecutando php artisan serve directamente en tu máquina local, a veces es la misma ruta que tu proyecto local, o si usas un entorno de servidor web (Apache/Nginx), la ruta a la raíz de tu sitio.

      • Para php artisan serve ejecutándose localmente sin Docker: La ruta en el servidor suele ser la misma que la ruta local de tu proyecto. Si tu proyecto está en C:\Users\MiUsuario\proyectos\mi-laravel-app, entonces la primera parte del mapeo podría ser C:\Users\MiUsuario\proyectos\mi-laravel-app.
      • "${workspaceFolder}": Esto es una variable de VS Code que representa la ruta de la carpeta raíz de tu proyecto abierta en VS Code.

    • Ejemplo de pathMappings para php artisan serve en tu máquina local: Si tu proyecto Laravel está en C:\Users\MiUsuario\Documents\Laravel\mi-app-laravel, tu pathMappings ideal sería:

      JSON
      "pathMappings": {
    "C:\\Users\\MiUsuario\\Documents\\Laravel\\mi-app-laravel": "${workspaceFolder}"
}

      (Asegúrate de usar barras dobles \\ en Windows o barras normales / en Linux/macOS).


Inicia el "escucha" de depuración en VS Code:

  • Ve a la vista "Ejecutar y Depurar" (Ctrl+Shift+D).
  • En el menú desplegable de configuraciones (en la parte superior, al lado del botón de play verde), selecciona "Listen for Xdebug".
  • Haz clic en el botón de play verde que está al lado.
  • VS Code ahora estará esperando una conexión de Xdebug en el puerto 9003. Verás una barra de herramientas de depuración flotante y la barra de estado de VS Code se volverá naranja/azul.
Sea cual fuere el IDE configurado, hay que setear breakpoints en los lugares donde se desea que se detenga la ejecución.
Luego hay que ir a la aplicación web y navegar hasta dar con la acción que coincide con los breakpoints que pusimos para que se detenga y podamos comenzar a depurar.
Publicado por en
Etiquetas: , , , , ,

No hay comentarios:

Publicar un comentario

Suscribirse a: Enviar comentarios (Atom)