Remote debug is not enabled / Wrong php.ini setting

[WalterWoshid]

• Sail Version: 1.13.6
• Laravel Version: 9.4.1
• PHP Version: 8.1.3
• OS: Windows 10 with WSL2

Description:

Trying to debug my application with the PhpStorm IDE does not work, this is the error message when trying to validate xdebug configuration:

Checking the php ini with sail php -i, I can see following: xdebug.mode => develop => develop

Reading the xdebug documentation I can see, that we can add multiple modes like this: xdebug.mode=develop,debug

My .env file:

SAIL_XDEBUG_MODE=develop,debug

[WalterWoshid]

Temporary solution:

• sail artisan sail:publish

Add following to your ./docker/8.1/php.ini file:

[Xdebug]
xdebug.mode=develop,debug

• sail stop && sail up -d --build

[driesvints]

It's indeed the idea that you edit your ini settings to whatever you need.

[WalterWoshid]

@driesvints It would be nice to have this automatically configured.

I looked way too long to 1. find out you can modify the php.ini by using sail artisan sail:publish and 2. why there is SAIL_XDEBUG_MODE=develop,debug if it does not do anything (not sure about that)

Just my suggestion, it wouldn't really destroy anything and you could still override the setting with the php.ini :)

[driesvints]

Feel free to attempt a PR 👍

[WalterWoshid]

358

[christianblueskylabs]

@WalterWoshid You might want to keep this open as it is still an outstanding issue. I agree that the documentation should be much more clearer about this, but I also think that there is something amiss about Xdebug 3's documentation as it doesn't seem to allow you to override it via environment variables.

After a few tests, I observed that overrides in XDEBUG_MODE only works if you define the master value first by declaring it in the .ini files. It doesn't have to be the value you want, it only needs to exist. Then when you set XDEBUG_MODE, it will override the master value as a local value, over any declaration made on XDEBUG_CONFIG. Maybe it's worth checking in Xdebug 3 issue tracker for this?

I saw your PR, and based on this information, it seems that it did not need that many changes, because simple adding the key/value into any value in php.ini will be enough for it to be overriden by XDEBUG_MODE.

I'm still not overly successful with using Xdebug here, but I don't blame Laravel for it as my issues right now seem to be wildly about Docker. The internet also isn't helping as nobody seems to have fully demonstrated a working WSL + Docker + PHP/Xdebug 3 setup working yet, at least for my case. If I do get some luck, I'm happy to pour in doco for it.

[WalterWoshid]

@christianblueskylabs see https://github.com/laravel/sail/pull/358#issuecomment-1068243161

[saulens22]

I'm still not overly successful with using Xdebug here, but I don't blame Laravel for it as my issues right now seem to be wildly about Docker. The internet also isn't helping as nobody seems to have fully demonstrated a working WSL + Docker + PHP/Xdebug 3 setup working yet, at least for my case. If I do get some luck, I'm happy to pour in doco for it.

OK @christianblueskylabs , I'll demonstrate my successful WSL2 + Docker + PHP 8.1 + Xdebug 3.1.4 + VSCode :)

1. Publish runtime you want with sail artisan sail:publish
2. Add this to php.ini and then rebuild container with sail build --no-cache:

   [XDebug]
   xdebug.mode = debug
   xdebug.start_with_request = yes
   xdebug.discover_client_host = true
   xdebug.idekey = VSC
   xdebug.client_host = host.docker.internal
   xdebug.client_port = 9003
   xdebug.log_level = 0

3. Add these config options to docker-compose.yml if they don't exist:

   services:
   laravel.test:
      [...]
       extra_hosts:
           - 'host.docker.internal:host-gateway'
       environment:
           XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
           XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'

4. Add this to .env if it doesn't exist (or any other mode):

   SAIL_XDEBUG_MODE=debug

5. Create .vscode/launch.json file and add this config:

   
   {
   "version": "0.2.0",
   "configurations": [
       {
           "name": "Listen for XDebug on Docker App",
           "type": "php",
           "request": "launch",
           "port": 9003,
           "pathMappings": {
               "/var/www/html": "${workspaceFolder}"
           },
           "hostname": "localhost",
           "xdebugSettings": {
               "max_data": 65535,
               "show_hidden": 1,
               "max_children": 100,
               "max_depth": 5
           }
       },
   ]
   }

6. Launch VSCode listener and then start Sail
7. Profit :)
![image](https://user-images.githubusercontent.com/9000854/166682134-8717709a-9a9d-4c6a-a71a-7c5e09cd6efb.png)

[WalterWoshid]

@saulens22 I think the problem is not that the debugger doesn't work, its about the .env file not using the "SAIL_XDEBUG_MODE" variable. It does absolutely nothing, but in my pull request I made sure that the pre-defined php.ini uses this env variable.

[saulens22]

@WalterWoshid incorrect. SAIL_XDEBUG_MODE sets XDEBUG_MODE env variable in container: https://github.com/laravel/sail/blob/8cf8bbf8add4a39618be5f97b772488e2acf2f23/stubs/docker-compose.stub#L19

Xdebug then uses that env value even if defaults are not set. No php.ini editing needed. It's important to set SAIL_XDEBUG_MODE and not XDEBUG_MODE directly in .env

I just tested and can confirm this. More info on testing: https://stackoverflow.com/a/65107622/2506492

Custom php.ini directives are needed to set custom xdebug.client_host and xdebug.client_port, though.

[WalterWoshid]

@saulens22 But that was the point of my issue. I couldn't get Xdebug to run on Windows 10 without manually editing the php.ini. See the picture which I have provided.

I'll have to do some testing on that again.

[christianblueskylabs]

@saulens22 Hey mate, apologies if this is 4 weeks late and I appreciate the effort. I was actually able to make it 100% work but I just snoozed over this PR when I figured out everything the night I last commented, even @WalterWoshid's issue.

There are actually two things in play here:

1. the env var SAIL_XDEBUG_MODE does not work on specific versions of laravel/sail. I am 100% on this as I dragged it over the coals but it was on version ^1.13. However, I tried this env var on a very fresh installation of Laravel the night I last commented and can confirm that SAIL_XDEBUG_MODE does work on that setup. I cannot confirm which version I was using at the moment as I do not have that machine with me right now.
2. Like what I have said, these issues are compounded with the fact that WSL is being used. Why WSL has a part on it? it can easily be explained by this stack overflow post: https://stackoverflow.com/questions/63898430/how-can-i-access-a-service-running-on-wsl2-from-inside-a-docker-container

How I made it work

I did not really have to change a lot in the config other than setting SAIL_XDEBUG_MODE to the correct value. It works 100% out of the box provided the test setup I had at that time. However, point 2 raises a very important consideration in it.

If you run vscode and the debugger from WSL 2 (by running code . on your project of choice from presumably WSL Ubuntu shell), it will not work unless you port forward 9003 (or whichever choice of port) from the windows machine onto the port that vscode in WSL is running the debugger in.

If you run vscode from Windows (you can tell because the green WSL indicator on the lower left of vscode will not be on) and run your debugger, it will work unless you have Windows Firewall on set to being overzealous.

Hope it helps!