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:
- The ones who use dd or console.log() to debug and
- 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.
Top comments (2)
If you add a breakpoint to a blade component template and it's not triggering, it's because blade templates are compiled into the storage/framework/views folder. So, the file you're looking at in your IDE is not the one running on the server.
So, you can find the file in the stack of compiled and add a breakpoint there, and it will trigger.
The problem is the files are named with MD5-type names, so it might take a minute to find your file. Additionally, the breakpoint will trigger about 20 times (I've not figured this one out yet).
Compiled they are not. Efficient they most certainly are not.
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