How to debug like a pro using Xdebug, PHPStorm, and Docker.

What is XDebug?

Xdebug is an extension for PHP and provides a range of features to improve the PHP development experience.

Step Debugging

A way to step through your code in your IDE or editor while the script is executing.

Improvements to PHP’s error reporting

An improved var_dump() function, stack traces for Notices, Warnings, Errors, and Exceptions to highlight the code path to the error


Writes every function call, with arguments and invocation location to disk. Optionally also includes every variable assignment and return value for each function.


Allows you, with the help of visualization tools, to analyze the performance of your PHP application and find bottlenecks.

Code Coverage Analysis

To show which parts of your codebase are executed when running unit tests with PHP Unit.

Install and Configure Xdebug

In a dockerized app, you need to install Xdebug and configure the debugger in your Dockerfile like below;

pecl install xdebug; \
docker-php-ext-enable xdebug; \
echo "error_reporting = E_ALL" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "display_startup_errors = On" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "display_errors = On" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.remote_enable=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.mode=develop,trace,debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.start_with_request = yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.discover_client_host=1" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.client_port=9003" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20200930/" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \
echo "xdebug.idekey=PHPSTORM" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini; \

Setup a server in PHPStorm

  • Click on the PHPStorm icon and select preference.
  • Click on PHP then click on the server
  • Name your server
  • Type localhost as Host
  • Select Xdebug
  • Check path mapping
  • Click ok

Configure Xdebug

  • Click on the PHPStorm icon and select preference.
  • Click on Debug and configure Xdebug
  • Select all the options under Xdebug

Install Browser debugging extensions

Next is to set up browser listeners for the Xdebug. There are a couple of plugins that can help you trigger a session when Docker sends a signal to PHPStorm.

Start Listening

Browser debugging extension
place a stopover
Debugger Tab



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store