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

Building an application as a developer can be fun sometimes. It can also be a pain especially when you encounter a bug, and you couldn’t locate where the bug is being introduced.

Developers often make use of var_dump() and dd() to view what value is passed to the function and why the value is not returning the right result. This can be time-consuming and inefficient as you have to keep refreshing your browser to see the results.

In this article, I’m going to show you how to configure Xdebug with PHPStorm and Docker to debug like a pro.

What is XDebug?

Step Debugging

Improvements to PHP’s error reporting



Code Coverage Analysis

Install and Configure Xdebug

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; \

When you run docker compose up -d Xdebug will be installed and the Xdebug configuration would be exported to the php.ini You can check if Xdebug has been set up for you.

Run docker ps to view the container name and docker exec -it container-name /bin/bash or docker exec -it container-name /bin/sh if you are using the alpine image.

In your container, type php --version and you should see the PHP version and the Xdebug version like below;

PHP 8.0.3 (cli) (built: Apr 10 2021 13:25:28) ( NTS )
Copyright © The PHP Group
Zend Engine v4.0.3, Copyright © Zend Technologies
with Xdebug v3.1.1, Copyright © 2002–2021, by Derick Rethans

The next step is to configure PHPStorm.

Setup a server in PHPStorm

  • 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 Debug and configure Xdebug
  • Select all the options under Xdebug

Install Browser debugging extensions

You can install anyone for your preferred browser here and follow the instructions.

Start Listening

Once you have completed the above steps, then click on the call icon, it should turn green. Now you can go to your browser and click on the debug extension browser icon and select Debug.

Browser debugging extension

Place a step on any line in your editor and refresh your browser. And you should receive a request in your PHPStorm editor as shown below;

place a stopover
Debugger Tab

The next thing is to start using the debugger tab to debug your code.

If you would like to learn how to use the debugging functions such as a step into, step to next, etc in PHPStorm, you can follow this short tutorial on LaraCast.

Thanks for taking the time to read this article. I hope this helps someone to debug faster.

Feel free to drop a comment if you have any feedback.

Software Developer @andela | Music Lover | Data Science Enthusiast.