PhpStorm Docker Compose interpreter and Xdebug path‑mapping ownership

Interoperability boundary

When a project uses a docker-compose.yml service as the PHP CLI interpreter in PhpStorm, the IDE derives container paths from the compose volume mounts and working_dir. At the same time, Xdebug 3 expects matching path mappings in Settings > PHP > Servers and container‑side environment variables such as XDEBUG_MODE, XDEBUG_CLIENT_HOST, and XDEBUG_CLIENT_PORT. The repeatable‑environment goal is to keep a single source of truth for both the runtime and the debugger connection.

Open questions

• Which component — PhpStorm’s interpreter configuration or the compose file — should be considered the authoritative owner of the host‑to‑container path mapping?
• How can a team guarantee that the IDE‑side server mapping stays in sync with compose interpolation (e.g., ${VAR} or .env files) across PhpStorm releases and Docker Compose v2 versus the standalone binary?
• What verification steps expose a mismatch before a debugging session times out?