CodexBloom - Programming Q&A Platform

Trouble with Local Development Environment for PHP with Docker and Xdebug

👀 Views: 146 💬 Answers: 1 📅 Created: 2025-10-05
docker xdebug php phpstorm development PHP

I'm experimenting with I'm stuck on something that should probably be simple. Recently started working with a project that utilizes Docker for PHP development. I'm trying to set up an environment that includes Xdebug for debugging, but I’m running into some challenges. My Docker setup uses PHP 8.1 and I want to ensure that Xdebug is properly configured to work with my IDE, which is PHPStorm. In my `docker-compose.yml`, I have the following: ```yaml version: '3.8' services: php: image: php:8.1-fpm volumes: - ./src:/var/www/html ports: - "9000:9000" environment: PHP_IDE_CONFIG: "serverName=localhost" XDEBUG_MODE: "debug" XDEBUG_CONFIG: "client_host=host.docker.internal" ``` However, after starting my Docker containers, Xdebug doesn’t seem to hit any breakpoints in PHPStorm. I’ve already verified that my Docker container can reach my host’s IP, and I’ve set up the path mappings correctly in PHPStorm, pointing `/var/www/html` to my local `src` folder. I also added the following to my `php.ini`: ```ini [xdebug] xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=host.docker.internal xdebug.client_port=9003 ``` The PHPStorm logs indicate that Xdebug is attempting to connect, but it often shows a message indicating it cannot establish the connection. I've tried various configurations, including changing the `client_host` to the actual IP address of my host machine instead of `host.docker.internal`, but that didn’t work either. Additionally, I've made sure my firewall settings allow traffic through port 9003, which is the default port for Xdebug. Is there something I might be missing in my configuration, or is there a recommended best practice for setting up Xdebug with Docker and PHP 8.1 that could resolve this issue? Any ideas what could be causing this? I'm coming from a different tech stack and learning Php. Thanks for taking the time to read this!