Debug Laravel unit test in Docker with Xdebug and Phpstorm

Also, learn how to debug Laravel artisan command here and debug Laravel web application here.

Find yourself spending too much time on a clunky workaround just to output some values to the console for debugging purpose? Switch to step-by-step code execution, breakpoint-based debugging using IDE (PHPStorm) and XDebug to save time and your sanity. This article will guide you through how to achieve that when you need to debug your Laravel unit test in a Docker container.

1. Install Xdebug plugin for PHP and config Xdebug to play well on Docker

Double-check if the PHP version installed in your Docker container already has Xdebug (by using command php -v and see if the output says anything about Xdebug). If you don't already have Xdebug installed, you need to install it before continuing. Way to install xdebug varies as per environment and php distribution, however if your environment is using php 7.4 or newer, chance that pecl install xdebug should suffice.

After installing Xdebug, create a file named xdebug.ini under /<installed php folder>/conf.d/ and save these lines into it (note that you can use php --ini to know where your php configs are located at):

# For Xdebug version 2.x
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1
xdebug.idekey=PHPSTORM
xdebug.remote_host=host.docker.internal
xdebug.remote_port=9001 # or any other arbitrary port

# For Xdebug version 3.x
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
# default port is 9003

Next, docker-compose <your laravel service> restart (or if you don't use docker-compose then it should be docker container <your laravel container> restart) to restart the container and make the changes take effect.

Finally, verify that the PHP > Debug section in your PHPStorm setting to make sure that the Xdebug port there points to the same port you defined in the xdebug.ini file.

2. Config the PHPStorm CLI interpreter

This should be very straightforward. In the PHP section in PHPStorm setting, create a new CLI interpreter config from your docker/docker-compose setting. PHPStorm will import the settings and magically getting CLI interpreter configs into place.

If you opt to configure a new CLI, verify that the IDE correctly detects the interpreter executable and debugger availability status after configuration.

3. Set breakpoint inside your unit test class, and start debugging process

Open your unit test class file, and set breakpoint in the place you see fit. For example, here is my dummy unit test class file and I have put a breakpoint.

You can see, the unit test execution stopped at the breakpoint, conveniently displaying all the variables' values.

Compared to Laravel Artisan command and web application debugging, setting up PHPStorm for unit test debugging is very easy and minimal, because all you're required to do is just configuring PHPStorm's PHP intepreter. When you click the button "Run/Debug ", PHPStorm invokes the intepreter in the Docker container and executes your test case, simple as that!

You can also learn how to debug Laravel artisan command here and debug Laravel web application here.