DEV Community

Cover image for Laravel Sail & XDebug

Posted on • Updated on

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.


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

Image description

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:
Enter fullscreen mode Exit fullscreen mode

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'

Image description

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

Image description

Choose the option PHP Remote debug

Image description

Give your debug config a name

Image description

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 or localhost

Image description

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.

Image description

Click OK and you're likely set to go.

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

Image description

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:

Image description

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.

Top comments (1)

dr41d45 profile image
Info Comment hidden by post author - thread only accessible via permalink

totally nonsense to edit docker-compose with the extra volume of ini file. Everything works out of the box with Laravel's Sail. All XDEBUG_ parameters can be placed in ENV file and works smoothly.

Some comments have been hidden by the post's author - find out more