Setting up Xdebug in Docker

When searching how to integrate Xdebug into my Docker workflow, I hit a blocker on how to reach it outside the Docker container. The container itself knew Xdebug was there, but tools like PHPStorm couldn’t reach the extension.

Even after following the instructions on PHPStorm’s zero configuration debugging help page, I couldn’t reach Xdebug. Something was missing. The answer was frustratingly simple…my php.ini was missing a few lines.

PHP.ini Confguration#

Inside the container’s php.ini, these lines made all the difference:

    

        BASH
        Copy to clipboard
    
    
        
zend_extension=xdebug.so  # Might need to check extension path
xdebug.remote_enable=1
xdebug.remote_host=172.17.0.1  # container IP address
xdebug.remote_port=9001

    

Extra PHP.ini configuration

Instead of debugging or profiling all PHP calls, you can be more selective by using a cookie, Xdebug bookmarklet or extension, and a few more lines of configuration in the container’s php.ini file.

    

        BASH
        Copy to clipboard
    
    
        
xdebug.remote_handler=dbgp  # Enables use of cookie
xdebug.remote_mode=req
xdebug.remote_autostart=0
xdebug.remote_connect_back=0
xdebug.idekey = PHPSTORM  # Name of the cookie
xdebug.remote_log=/tmp/xdebug.log  # Useful logs for troubleshooting

    

Tips & Tricks#

• Go to https://www.jetbrains.com/phpstorm/marklets/ or use Xdebug Helper extension.
• If using Apache in your container, sometimes restarting Apache is required for changes to take effect.
• Unsure of your configuration? Paste your container’s phpinfo() output into https://xdebug.org/wizard.
• Tools like Docksal have a configuration file where enabling xdebug is as simple as changing 0 to 1.