Xdebug on macOS
Due to the way networking is implemented with Docker for macOS, the Xdebug "remote_connect_back" method does not work. See https://xdebug.org/docs/remote#communication for an explanation of the two different ways that Xdebug communicates with your IDE/Editor.
On Linux, the host can directly communicate with the containers, and vice versa. This way, Xdebug in the container can connect back to the IDE. On macOS, the containers run in a hidden Linux VM, which is why networking is a bit more complicated (explained here: https://docs.docker.com/docker-for-mac/networking/#there-is-no-docker0-bridge-on-macos). From the view of the container, the IP doing the request is not actually the host IP, but of the Linux OS in the VM. Obviously, the open port waiting for an Xdebug connection will not be present on the Linux VM. Because of this, Xdebug must know the actual IP of the macOS host (which is reachable from containers, just not predictable) beforehand.
The "solution" for macOS consists of modifying the xdebug configuration like this:
[...]
xdebug.remote_autostart=1
xdebug.remote_connect_back=off
xdebug.remote_host=host.docker.internal
On Docker for macOS, host.docker.internal
will always resolve to a current (internal) IP of the macOS host.
However, the special DNS name host.docker.internal
only works on Docker for macOS (https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). Evidently, this would break debugging at least on Linux, so just modifying /docker/conf/app/php.dev.ini is not an option.
Possible fixes
- Provide alternative config files that a macOS developer can use manually
- Extend setup scripts to copy the appropriate file (have the platform-specific configs in Git, copy them and .gitignore the actual file used by the container)
Other considerations
- How does debugging work on Windows right now? Does it even work at all?