Is the Laravel Sail xDebug documentation correct?

[iwasherefirst2]

Today I tried the new xDebug feature from Sail and I stumbled on this paragraph:

Internally, the XDEBUG_CONFIG environment variable is defined as client_host=host.docker.internal so that Xdebug will be properly configured for Mac and Windows (WSL2). If your local machine is running Linux, you will need to manually define this environment variable.

First, you should determine the correct host IP address to add to the environment variable by running the following command. Typically, the should be the name of the container that serves your application and often ends with _laravel.test_1:

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}}
Once you have obtained the correct host IP address, you should define the SAIL_XDEBUG_CONFIG variable within your application's .env file:

SAIL_XDEBUG_CONFIG="client_host="

I tried to follow these instructions, because I am using Ubuntu 18.04. It was pretty hard, because you need to know the host-ip-address before you start the container. I only managed to do this by restarting the container a couple of times until I saw a pattern and was able to guess the next container ip.

I also tried to use client_host=host.docker.internal (by removing SAIL_XDEBUG_CONFIG from env) and it just worked fine on Ubuntu. This makes me wonder, is the first paragraph actually true? Or can the whole section Linux Host IP Configuration in xDebug section be removed?

[TactiFail]

I'm thinking you may be right.

TL;DR - As far as I can tell, all you need to do (assuming you are on Laravel 8 using Sail) is set SAIL_XDEBUG_MODE=develop,debug in your .env and run sail build --no-cache to rebuild, then sail up to run. I have tested this on an Ubuntu 20.04 server and a Macbook Pro running Big Sur 11.8 with practically identical configurations.

My setup:

• Laravel 8 using Sail on an Ubuntu 20.04 server with Docker version 20.10.8
• Windows 10 desktop running Visual Studio Code, remotely editing over SSH to above server
• Google Chrome with the Xdebug helper extension installed, and the IDE key set to VSCODE
• My Laravel .env has: SAIL_XDEBUG_MODE=develop,debug but NOT SAIL_XDEBUG_CONFIG="client_host=<whatever>"
• My VS Code launch.json for the PHP Debug extension:

        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            },
            "xdebugSettings": {
                "max_data": 65535,
                "show_hidden": 1,
                "max_children": 100,
                "max_depth": 5
            }
        },

I did a sail build --no-cache after adding SAIL_XDEBUG_MODE=develop,debug to .env and then sail up. I ran the Listen for Xdebug command in VS Code, and set the Xdebug helper extension in Chrome to Debug.

I put a breakpoint on one of the Route::get calls in my web.php file and reloaded the page in Chrome. VS Code halted for a moment then worked as expected. I could step into, out of, over, etc.

I had played around with various values in the SAIL_XDEBUG_CONFIG="client_host=<whatever>" setting, rebuilding the containers each time, and nothing seemed to matter. It was only once I removed it entirely that it worked.

I also have a Macbook Pro running Big Sur 11.6, with Docker (also version 20.10.8) running locally and php8 installed. Also running VS Code, and has the same Laravel Sail setup as above with the same codebase pulled from a shared GitLab repo. That .env file also does not have the SAIL_XDEBUG_CONFIG setting, and the launch.json is the same except that hostname is localhost and I changed the pathMappings because the code is in a specific subdirectory on the Macbook. Works great, even faster I suspect since the Xdebug traffic doesn't have to traverse my network.

Edit to add: This might also be dependent upon your Docker version. Apparently the host.docker.internal stuff only works with version 20.04 or later. I have not tested with any other versions.

Source: https://stackoverflow.com/a/61424570/5607109

[ianmackay123]

Thank you so much - I've been struggling with this for days, and couldn't understand why breakpoints just weren't working in VScode for me.. following what you did got it working. Eternally greatful!

[nazaretk]

I think the documentation indeed needs to be updated. Firstly, as mentioned by @iwasherefirst2 you have to know the host-ip-address before you start the container, and I'm not sure if this is even possible since the IP is assigned after starting the container.

Secondly, in recent versions of the docker engine (from 20.04 I think, you may see the github discussion here), the gateway address can be exposed on linux (Docker for Mac and Windows already exposed the host.docker.internal hostname), and this is already supported by Sail 1.12.12, since the docker-compose.yml that is created by Sail includes the host.docker.internal in extra_hosts (see PR here).

Therefore, when running xdebug client (e.g. VSCode) on the host machine and using the current versions of Docker and Sail (I'm using Sail 1.12.12 (using docker image laravelsail/php81-composer:latest), Docker 20.10 and Docker compose 1.29.2 on Linux), the SAIL_XDEBUG_CONFIG doesn't need to be overriden at all in .env. The default value host.docker.internal passed in the Sail generated docker-compose works fine.

Furthermore, since Sail supports Devcontainer and also includes documentation about it, I would suggest that the documentation should also mention the option of debugging using a Devcontainer. In this case, the xdebug client listens within the app container, therefore the SAIL_XDEBUG_CONFIG needs to be overriden in .env, like so:

SAIL_XDEBUG_CONFIG="client_host=localhost"

This setting allows xdebug to connect to VSCode which is connected to the devcontainer.

Let me know what you think, I could open a PR.

[iwasherefirst2]

This has been addressed now laravel/docs#9887 (comment)