PhpStorm Docker Compose interpreter and Xdebug path‑mapping ownership

Owner of the path mapping

The docker-compose.yml service definition is the authoritative owner of the host-to-container path mapping. Volume mount targets and working_dir determine where files exist inside the container. PhpStorm's Docker Compose interpreter and Settings > PHP > Servers path mappings are mirrors of that runtime layout; Xdebug 3 environment variables control whether and where the debugger connects, not the path mapping.

Confirmed facts

• Compose volume targets and working_dir define container paths.
• PhpStorm derives interpreter mappings from Compose, but may not resolve .env or shell interpolation identically to docker compose config.
• Xdebug 3 uses Settings > PHP > Servers path mappings to map the container path reported during execution back to a local file.
• XDEBUG_MODE, XDEBUG_CLIENT_HOST, and XDEBUG_CLIENT_PORT do not encode host-to-container paths.

Likely explanation

Breakpoints miss or open the wrong file when the Compose file changes a mount target or working_dir and PhpStorm's Server mapping is not updated. Case sensitivity on Linux, trailing-slash differences, and different interpolation for host paths in Compose versus PhpStorm are common causes.

Steps for this case

1. Run docker compose config from the project root and record the resolved volume target and working_dir for the PHP service.
2. Use absolute host paths or project-relative paths resolved from the same base directory in Compose and PhpStorm. Do not interpolate the host path differently in .env and IDE mappings.
3. In PhpStorm, open Settings > PHP > Servers, add or edit the server, and set Path mappings so the local project path maps to the exact Compose container target from step 1. Match case and trailing slashes exactly.
4. Open the Docker Compose PHP CLI interpreter and confirm its path mapping matches the same Compose target. Do not edit the interpreter mapping to override Compose volumes.
5. Set Xdebug 3 in the Compose service environment:

environment:
  XDEBUG_MODE: develop,debug
  XDEBUG_CLIENT_HOST: ${XDEBUG_CLIENT_HOST}
  XDEBUG_CLIENT_PORT: 9003

Verification before a debug session

• Compare docker compose config output with PhpStorm Settings > PHP > Servers path mappings and the Compose interpreter mapping.
• Run through the PhpStorm CLI interpreter. The echoed container path must appear as a Server mapping target.
• Run php -m | grep -i xdebug to confirm the extension is loaded, and run nc -zv $XDEBUG_CLIENT_HOST 9003 from inside the container to confirm the client host is reachable.

Assumption: PhpStorm uses Docker Compose v2 (docker compose) on a Linux host. On Linux, prefer the Docker host-gateway address for XDEBUG_CLIENT_HOST; host.docker.internal is unreliable there. If you use standalone Compose v1 or Docker Desktop on Mac/Windows, replace docker compose with docker-compose and use the host address for that platform. If the reachability check fails, report host OS and Compose integration before changing mappings, because that changes the correct host address.