Debug PHP with VSCode and Docker
Setting up Xdebug between a PHP container and VSCode often feels like solving a puzzle where the pieces don't fit until you realize the puzzle board itself is tilted. The core issue usually isn't missing configuration flags, but rather a fundamental misunderstanding of how network traffic flows between containers, the host machine, and your IDE.
When you run PHP on WAMP or XAMPP, the debugger sits on the same network stack as your editor. You open a file, set a breakpoint, and VSCode connects back to localhost:9000. Inside Docker, however, localhost inside the container refers to the container itself, not your Mac or Windows machine. That is why xdebug.remote_connect_back=0 combined with host.docker.internal (or 172.17.0.1) is critical; Xdebug needs to know exactly where to listen for the VSCode debugger client.
The most common stumbling block involves port mapping in your docker-compose.yml. In your initial setup, you exposed port 9000 on the host (- 9000:9000). This creates a conflict if you are not running a standard HTTP server listening on that port. Xdebug is a protocol used to communicate with an IDE, not typically something served directly via Apache's default ports without specific configuration.
If you map port 9000 in Docker Compose while using the xdebug.ini file provided:
xdebug.remote_port=9000
xdebug.remote_connect_back=0
xdebug.remote_host='host.docker.internal'
You are telling Xdebug to wait for a connection on port 9000 inside the container. However, if you also expose this port to the host network in Compose, and VSCode tries to connect back to 127.0.0.1:9000, it might hit your Apache listener or nothing at all depending on how the stack is initialized. The error logs showing Time-out connecting to client indicate that Xdebug inside the container is actively waiting for a handshake from VSCode, but the connection is never established.
The solution often lies in removing the explicit port mapping for 9000 in your docker-compose.yml. Unlike web ports (80, 443) or database ports which require exposure to function, Xdebug acts as a listener that initiates the handshake only when code execution triggers it. By removing - 9000:9000, you allow Xdebug to bind to host.docker.internal inside the container without creating a local port conflict or ambiguity on the host machine.
Inside your VSCode launch.json, ensure your configuration matches the Xdebug settings strictly. When using request: "launch", the debugger is proactive; it waits for the PHP script to call back to the IDE. Your path mappings must be accurate. If your Docker container mounts your code at /srv/app/cms, and your VSCode project root is my.app/cms, the mapping in launch.json should reflect that:
"pathMappings": {
"/srv/app/cms": "${workspaceFolder}"
}
Note that ${workspaceRoot} refers to the folder where the .vscode file sits, not necessarily the Docker mount point. If these paths do not align, VSCode cannot map the source code lines back to the container's internal state, causing breakpoints to appear as if they are ignored.
Another frequent oversight is the xdebug.remote_autostart=1 setting. This tells Xdebug to automatically trigger a connection whenever a script starts, which is convenient for development. However, if your application relies on a specific entry point defined in an autoloader or a bootstrap file, ensure that code runs before any output buffering issues arise.
Finally, verify that the xdebug.ini file is actually loaded inside the container. In your Dockerfile, the command docker-php-ext-enable xdebug is crucial. Without this step, Xdebug remains compiled but inactive. The log entry [xdebug] confirms the configuration block exists, but if the extension isn't enabled at runtime, the debugger will fail to attach regardless of network settings.
By aligning the host path mappings, ensuring the container listens on host.docker.internal, and removing unnecessary port exposes for the debug protocol, you can restore the seamless debugging experience lost when migrating from a local stack to Docker.