xdebug docker on macOS with PhpStorm

README.md

Use xdebug with docker on macOS and PhpStorm

To use xdebug with macOS and docker is quite, let´s call it tricky ;)

The following steps need to be proceed to get it working:

1. use the config from the xdebug.ini wihtin your docker web container. Important: set remote_connect_back to off

UPDATE

As mentioned by some comments (thanks for the feedback), it is not needed to configure the IP manually. Thus, the next step is optional and the configuration (xdebug.ini) is updated to use the dynamic IP.

2. optional: set up an alias for your local interface (lo)

To bring up the alias at startup, you can either (sudo may be needed here):

• manually place the file com.manuelselbach.docker_10254254254_alias.plist into directory: /Library/LaunchDaemons/

• Or use the script set_and_install_autorun_alias_for_lo.sh

Configure PhpStorm

After all that, just configure your PhpStorm:

1. set port for xdebug Preferences -> Languages & Frameworks -> PHP -> Debug | Xdebug: Debug port = 9005
2. configure a configuration in the toolbar

• use PHP remote Debug
• add a server to your domain (without protocoll like http:// or https://)
• set port for http / https (not the xdebug port here)
• select Debugger: Xdebug
• if needed: set path mappings

3. set Ide key (session id): to PHPSTORM

Happy debugging with docker!

com.manuelselbach.docker_10254254254_alias.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.manuelselbach.docker_10254254254_alias</string>
    <key>ProgramArguments</key>
    <array>
        <string>ifconfig</string>
        <string>lo0</string>
        <string>alias</string>
        <string>10.254.254.254</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

set-alias-for-lo.sh

#!/bin/bash

ifconfig lo0 alias 10.254.254.254

set_and_install_autorun_alias_for_lo.sh

#!/bin/bash

ifconfig lo0 alias 10.254.254.254

curl https://gist.githubusercontent.com/manuelselbach/8a214ae012964b1d49d9fb019f5f5d7b/raw/fc57a5c8f13c6f9deb64d70f992a29487c49e494/com.manuelselbach.docker_10254254254_alias.plist  >> /Library/LaunchDaemons/com.manuelselbach.docker_10254254254_alias.plist

xdebug.ini

# xdebug config within docker container
zend_extension=/path/to/xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.remote_connect_back=off
xdebug.remote_host=host.docker.internal
# xdebug.remote_host=10.254.254.254 ## use this to configure it manually
xdebug.remote_port=9005
xdebug.idekey=PHPSTORM
xdebug.max_nesting_level=1500

Should xdebug.remote_host be the ip address of the container?

I have a suggestion. If you set xdebug.remote_host=docker.for.mac.localhost, you don't have to configure 10.254.254.254.
Check this discussion if you want to know why.

It should work xdebug.remote_host=host.docker.internal
But I have found out, that it works occasionally. No idea why.

Works for other IDEs too. For Visual Studio Code just change the xdebug.idekey=VSCODE and you are good to go.

Thank you for all the information! It works like a charm.
xdebug.remote_host=docker.for.mac.localhost or xdebug.remote_host=host.docker.internal work fine for me.

Thank you.

Important: set remote_connect_back to off

This saved my life 🙏

I have a suggestion. If you set xdebug.remote_host=docker.for.mac.localhost, you don't have to configure 10.254.254.254.
Check this discussion if you want to know why.

Helped me a lot, thanks !

Thanks, works like a charm and easy to setup, saved my time..

Thank you!
It helped me too!

Great Man, That Finally Worked, Actually For me 9005 was also not working, so had to change it to 9006

For those of you installing xdebug 3 :) some settings were changed!

this stackoverflow helped me out : https://stackoverflow.com/questions/64776338/xdebug-3-the-setting-xdebug-remote-has-been-renamed-see-the-upgrading-g

on mac, i used this setting :)
xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0