Debugging Laravel Sail on WSL2 with Xdebug and PhpStorm: A Practical Step-by-Step Guide

If you are developing Laravel inside WSL2 on Windows 11 using Laravel Sail (Docker) and your IDE is PhpStorm, getting Xdebug working can feel confusing. The official documentation historically left out a key step, especially for older Laravel versions (10 and lower), so many developers struggled with “Xdebug not connecting” problems.

Why Xdebug instead of dd() or var_dump()?

Tools like dd() and var_dump() are useful but limited.

With Xdebug you can,

• Pause execution at breakpoints
• View values in real time
• Step into/over functions
• Inspect call stacks
• Debug browser and API requests

Once configured properly, it is significantly faster and more powerful.

Step 1: Point Docker to your local php.ini

Open your docker-compose.yml file.

Update the context path to match your local PHP version folder, for example:

docker/8.2/php.ini

If you do not see the docker folder, publish Sail’s assets:

php artisan sail:publish

Make sure your PHP version in the path matches the one in docker-compose.yml (e.g., 8.1 vs 8.2).

Step 2: Edit docker/8.x/php.ini

Open docker/8.x/php.ini and update as below.

Then rebuild.

./vendor/bin/sail down
./vendor/bin/sail build --no-cache

Step 3: Enable Xdebug through .env

In your .env file add:

SAIL_XDEBUG_MODE=debug

If you need remove this line Xdebugger stay off.

Then restart Sail (no need to rebuild again):

./vendor/bin/sail down
./vendor/bin/sail up

Step 4: Configure PhpStorm debug port

Go to Settings → PHP → Debug

Confirm Debug port is 9003, and “Can accept external connections” is enabled.

Step 5: Configure server mapping in PhpStorm

Go to Settings → PHP → Servers

Add (“+”) a new server.

• Name: Sail
• Host: 0.0.0.0
• Port: 80
• Debugger: Xdebug
• Enable use path mapping

Then map your local project path to your project path, and absolute path to “/var/www/html”.

This mapping is essential so PhpStorm understands where container files live.

Step 6: Enable listening for connections

Click on the bug icon on the tool bar. This will start listening to debug requests.

Step 7: Trigger the debugger

Now let’s debugging. First set break point in a controller or route (or any where request will be reached).

Now you have two options to send debug request

1. Install Xdebug extension for the browser.

2. Use tool like Postman or from browser url section, send request to the API with “?XDEBUG_TRIGGER=1” query parameter.

If configuration is correct, PhpStorm will stop at your breakpoint.

Step 8: Quick test (optional but useful)

If you want to quickly verify Xdebug without configuring Postman or browser tools, enable Run → “Break at first line in PHP scripts” on tool bar menu.

Then reload any route. This will stop the request at the first php scripts. If this works your debugger is working!

Final thoughts

Xdebug with Docker, Sail, and WSL2 can feel complex because multiple layers interact:

• Windows host
• WSL2 Linux environment
• Docker container
• Laravel Sail wrapper
• PhpStorm IDE

Once the correct php.ini configuration and path mappings are in place, the setup becomes very stable and predictable. From that point onward, debugging Laravel becomes dramatically easier and faster than print-based debugging.

What’s next?

In the next part, I will walk through how to use a browser debugger together with Xdebug to create a full-stack debugging workflow. That guide will cover linking frontend requests, API breakpoints, and deep inspection across the entire request lifecycle.

Happy coding!