Debug Laravel artisan command in Docker with Xdebug and PHPStorm

Also, learn how to debug Laravel web application here and debug Laravel unit test here.

Find yourself having too many times adding and removing console output command just to inspect variables or process flow? 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 with the context of a Laravel app in a Docker container and about debugging an Artisan command.

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.

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
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9001

Next, docker-compose stop and docker-compose start (or if you don't use docker-compose then it should be docker container stop and docker container start respectively) 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. Setup debug configuration

The last step to get your interactive debugger working is to open Run/Debug Configuration and create a new "PHP Script" configuration. Refer to the image below.

The "File" should point to your local machine's Laravel artisan file.

In the "Arguments", type in your artisan command's parameters.

For the "Interpreter", select the CLI that you have configured in step 2 above.

After finishing all the settings, apply and OK, and we're good to go!

4. Set breakpoint, and start debugging process

Refer to the image below. I created a simple artisan command for this article (in fact, the content is exactly what make:command generates, plus some dead simple code for demonstration). After setting a breakpoint (as arrow 1 in the image), pressing "Start debug" icon (as arrow 2) to start the debug session.

The debugger should stop at the breakpoint, conveniently displays all variables' values up to this step. From here, you can execute code step-by-step, continue executing the program until the next breakpoint or stop executing altogether. Much more elegant and time-saving than logging debug messages to the console, no?

I hope this can help your Laravel artisan CLI app debugging session in Docker and PHPStorm become easier and more enjoyable.

You can also learn how to debug Laravel web application here and debug Laravel unit test here.