Laravel Sail & XDebug

Sailing on turbulent waters

Laravel Sail is a project focused on giving developers a dockerized environment without hassling with the internals of Docker.

I've been in contact with this project for some days and found it incredibly frustrating making XDebug work properly on PHPStorm.

Me being the Docker nerd I am, I started to mess with Sail's Docker image to make it work.

Why?

There are 2 kinds of developers:

1. The ones who use dd or console.log() to debug and
2. The ones who use debugging tools.

In my years of experience, the latter usually makes debugging faster and comprehensible. You can walk through the code line by line, inspect memory, check if conditionals are working, it has saved me days of headaches.

Okay, what's wrong with my Sail?

It seems like Sail's default config does not ship (pun intended) proper XDebug configuration for some environments (in my case, the env variables did not work at all). So, if you're not able to make it work the default way, come with me. Let's dew it.

Getting your hands dirty

Create a file called 20-xdebug.ini somewhere in your project. You can create a folder called docker, for example and add it to your .gitignore, so you don't commit config to your repository.

We are going to add a path mapping to the application container in docker-compose.yml

Considering you have added the file 20-xdebug.ini to a folder called Docker, add the following volume to your container:

- './docker/20-xdebug.ini:/etc/php/8.1/cli/conf.d/20-xdebug.ini'

(I assumed you're using PHP 8.1. If not, change the path version accordingly)

This command will map the file on your computer to PHP's XDebug config.

The file contents is as follows:

zend_extension=xdebug.so
[xdebug]
xdebug.start_with_request=yes
xdebug.discover_client_host=true
xdebug.max_nesting_level=256
xdebug.remote_handler=dbgp
xdebug.client_port=9003
xdebug.idekey=Docker
xdebug.mode=develop,debug
xdebug.client_host=host.docker.internal

This file sets the PHP to some default debug behaviors, like:

• Set the port of XDebug to 9003 (9000 might be busy with PHP-FPM or Node applications)
• Starts debugging with request
• Sets an IDE key, which is useful for PHPStorm's debug configuration
• Sets the client host to the gateway (your computer)

Among others :)

Now let's configure PHPStorm.

In the upper right corner, click on the debug options. Then on 'Edit configurations'

You'll be presented with a dialog. Click on add new configuration.

Choose the option PHP Remote debug

Give your debug config a name

Now click on 'Filter debug connection by IDE key' and click on the triple dot button of the servers option to add a new server.

Name your server Docker. To the host, add either 0.0.0.0 or localhost

Make sure to map your project's root directory to the container's /var/www/html.

Click OK. Then, on the previous dialog select the Docker server. Also, add the Docker IDE session key.

Click OK and you're likely set to go.

Select your Docker configuration for debug, and mind this icon:

When it's all green, it's listening to debug connections. If it's red, it's not listening. In this case, no breakpoints will be triggered.

Click on it to make it green.

You should be able to breakpoint through the project when you go sail up.

Some caveats

There's a default config of PHPStorm that really bothers me. For example, when you start a container, the routines executed firstly trigger the debugger without me asking for it.

To avoid this, go to PHPStorm's settings, then go in PHP>Debug.

Set it as following:

This will avoid accidental triggering of the debugger, for example, when the PHP server is starting. If it's not allowed to start, the process will hang, and you won't be able to run pages.

If you suspect there might be path mapping issues, tick back the 'Force break at first line if no path mapping is specified' option to check if you need to map something else. Then, untick it, because it can get pretty annoying.

That's it for today, kids.