EDIT-2 2018

The remote_host value can now be changed to support all platforms:

xdebug.remote_host = "host.docker.internal"

EDIT-1 2018 It's no longer needed to use the plist fix. As pointed out in this gist: https://gist.github.com/chadrien/c90927ec2d160ffea9c4#gistcomment-2398281 you can now use the docker for mac internal IP.

[xdebug]
xdebug.remote_host = "docker.for.mac.host.internal"
xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000
xdebug.idekey="PHPSTORM"

OLD CONFIG

Since you are using docker on a mac I'm posting the way my solution worked. Most of the credits go to this post on the docker forum.

Assuming your installation of xdebug is correctly, this is my config in the php.ini.

[xdebug]
xdebug.remote_host=10.254.254.254
xdebug.remote_autostart=1
xdebug.idekey = PHPSTORM
xdebug.default_enable = 0
xdebug.remote_enable = 1
xdebug.remote_connect_back = 0
xdebug.profiler_enable = 1

You can test your config by executing this command in your terminal. sudo ifconfig en0 alias 10.254.254.254 255.255.255.0.

If this is working you can convert it into a plist file and place it in the following location. /Library/LaunchDaemons/com.docker.xdebugFix.plist. Below you will find my version of the plist file.

<?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.docker.xdebugFix</string>
    <key>ProgramArguments</key>
    <array>
        <string>ifconfig</string>
        <string>en0</string>
        <string>alias</string>
        <string>10.254.254.254</string>
        <string>255.255.255.0</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Note: The plist will only work after a reboot of your Mac.

PHPSTORM Config (also needed after the 2018 edit)

After that I set up my PHP storm with a debug server like this:

After that my breakpoints where working, if you're using chrome you'll also need to use the xdebug extension but I'm pretty sure you know this since you used it in the past.

Check your docker-compose.yml

I had an environment variable in mine:

XDEBUG_CONFIG: remote_host=${LAN_IP}

that needed to be changed to:

XDEBUG_CONFIG: client_host=${LAN_IP}

where LAN_IP is defined as your local LAN IP in your .env file

I am working with VSCODE devcontainer and I use the config below:

My launch.json for VSCODE

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003
        }
    ]
}

I use Dockerfile with a RUN below to install xdebug:

RUN pecl install xdebug && docker-php-ext-enable xdebug

I find my xdebug config file in /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

I edit the file as below:

zend_extension=xdebug

[xdebug]
xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.start_with_request=yes
xdebug.idekey=VSCODE

Or you can add it in Dockfile like below:

RUN echo ' \n[xdebug] \n\
xdebug.client_host=host.docker.internal  \n\
xdebug.mode=debug  \n\
xdebug.start_with_request=yes \n\
xdebug.idekey="VSCODE"  \n\
\n' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

mode This setting controls which Xdebug features are enabled. We’ve set develop to enable development aids, such as getting better error messages, and debug to enable step debugging.

client_host This setting tells Xdebug the IP address or hostname of the machine that is running your text editor or IDE.

start_with_request This setting determines whether a function trace, garbage collection statistics, profiling, or step debugging are activated at the start of a PHP request. Setting it to yes instructs Xdebug to always initiate a debugging session.

Ref. https://matthewsetter.com/setup-step-debugging-php-xdebug3-docker/