Post actualizado el día octubre 29, 2026 by DeiviSanzPlay
Si intentas XAMPP depurar PHP con Xdebug y el depurador se queda colgado en «Waiting for incoming connection» o el breakpoint nunca se activa, el fallo casi siempre está en una combinación de tres cosas: el puerto 9003, la ruta pathMappings y la directiva start_with_request. No es la instalación, ni la versión de PHP. Es la configuración del archivo php.ini y de tu IDE.
He visto esta escena decenas de veces en entornos locales: XAMPP arranca Apache y MySQL sin quejarse, el navegador carga http://localhost/proyecto/index.php, pero PhpStorm o VS Code se quedan mirando al vacío con la barra de depuración activa. El código corre, pero el depurador no engancha. Ese es el síntoma. La causa suele ser más aburrida de lo que parece.
Xdebug 3 cambió las reglas y muchos tutoriales no
Desde Xdebug 3, la directiva xdebug.remote_enable=1 ya no existe. Ahora es xdebug.mode=debug. Si copiaste una configuración de un blog de 2019, tu php.ini está escrito para Xdebug 2 y por eso no pasa nada. Esta es la razón número uno por la que XAMPP depurar PHP con Xdebug falla en instalaciones nuevas.
La configuración mínima que funciona en XAMPP con Xdebug 3 tiene este aspecto:
[xdebug] zend_extension = «C:xamppphpextphp_xdebug.dll» xdebug.mode = debug xdebug.start_with_request = trigger xdebug.client_host = 127.0.0.1 xdebug.client_port = 9003 xdebug.log = «C:xampptmpxdebug.log»Fíjate en start_with_request = trigger. Con trigger, Xdebug solo se activa cuando la petición lleva la cookie XDEBUG_SESSION o el parámetro ?XDEBUG_SESSION_START=1. Si lo pones en yes, cada petición intentará conectar y ralentizarás tu navegación local. Si lo dejas en default, en algunos entornos no arranca nunca. Yo uso trigger casi siempre.
El log es tu mejor amigo, no tu IDE
Antes de tocar PhpStorm, abre C:xampptmpxdebug.log después de lanzar una petición. Si el archivo no existe, Xdebug no está cargado. Si existe pero dice «Could not connect to client on 127.0.0.1:9003», el problema es de red o de puerto. Si dice «Connected» y aun así no se detiene en el breakpoint, entonces sí es el IDE.
Este archivo de log es la diferencia entre adivinar y saber. Mucha gente configura XAMPP depurar PHP con Xdebug probando combinaciones al azar durante una tarde. Con el log, son cinco minutos.
Path mappings: el fallo silencioso
Cuando el log dice que la conexión se estableció pero el depurador ignora los breakpoints, casi siempre es por las rutas. Tu IDE abre el proyecto como /Users/tu-usuario/htdocs/proyecto o C:xampphtdocsproyecto, pero Xdebug reporta la ruta que Apache ve. Si no coinciden, el IDE recibe un archivo que no tiene abierto y descarta el breakpoint sin avisar.
En VS Code, dentro de launch.json, asegúrate de tener algo así:
«pathMappings»: { «/»: «${workspaceFolder}» }En PhpStorm, ve a Languages & Frameworks → PHP → Servers, marca Use path mappings y asigna la raíz del proyecto a la ruta absoluta que Apache usa. Si trabajas con un host virtual tipo proyecto.local, usa el mismo nombre en el servidor del IDE.
Esto no funciona igual si depuras con el navegador desde otra máquina de la red local. Ahí client_host tiene que apuntar a la IP de tu equipo en la LAN, no a 127.0.0.1, y tendrás que abrir el puerto 9003 en el firewall de Windows. Es un escenario menos frecuente, pero es donde más gente se atasca y culpa a XAMPP injustamente.
Un caso real que recuerdo bien
Hace un tiempo, un compañero tenía un proyecto Laravel en XAMPP. Todo funcionaba, pero el depurador solo se activaba en index.php y nunca en los controladores. El log mostraba conexiones correctas. Resultado: tenía xdebug.mode = debug,develop pero había añadido manualmente xdebug.remote_enable=1 al final del php.ini, sin borrar la línea anterior. Xdebug 3 ignoraba esa directiva, pero el IDE tenía marcada la opción «Force break at first line» y se detenía en cualquier sitio menos donde debía. La solución fue borrar el php.ini, dejar solo el bloque de Xdebug 3 y reiniciar Apache desde el panel de control de XAMPP. Nada más.
Moraleja: cuando XAMPP depurar PHP con Xdebug no responde, revisa primero el php.ini completo. Un solo zend_extension duplicado o una directiva legacy puede romperlo todo.
Lo que no arregla Xdebug
Xdebug no depura código que corre bajo otro SAPI distinto al de Apache. Si lanzas el proyecto con php artisan serve o con el servidor integrado de PHP, XAMPP no está involucrado y la configuración de xampp/php/php.ini no aplica. Ahí necesitas el php.ini del binario que estés usando. Tampoco funciona bien con opcache activo en algunos entornos, aunque es raro. Y no sirve para depurar peticiones AJAX si el navegador no envía la cookie de sesión de Xdebug; en ese caso tendrás que usar una extensión como Xdebug helper para Chrome o Firefox.
Si después de todo esto sigue sin funcionar, revisa que no haya otra instancia de Xdebug quejándose en los logs de Apache. A veces el problema no es la configuración, sino que el puerto 9003 está ocupado por otro proceso. Cambiar a 9004 en php.ini y en el IDE suele resolverlo.
Perfiles verificables: Sitio web
Publicado el 29 de October de 2026. Última revisión: 29 de October de 2026.
