How to enable Xdebug in Laravel Sail

How-to's How to enable Xdebug in Laravel Sail

1. Configure the SAIL_XDEBUG_MODE variable to the appropriate modes

.env

SAIL_XDEBUG_MODE=develop,debug,coverage

2. Publish Sail's docker files

sail artisan sail:publish

INFO  Publishing [sail-docker] assets.

Copying directory [vendor/laravel/sail/runtimes] to [docker] ..................................... DONE

INFO  Publishing [sail-database] assets.

Copying directory [vendor/laravel/sail/database] to [docker] ..................................... DONE

3. Ensure that the build context points to the correct service configuration

docker-compose.yml

services:
    laravel.test:
        build:
            context: ./docker/8.3
            dockerfile: Dockerfile
            ...

4. Create ext-xdebug.ini file with the following configuration

docker/8.3/ext-xdebug.ini

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=VSCODE
xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.var_display_max_depth=5

5. Add the following line to the Dockerfile to include the Xdebug configuration

docker/8.3/Dockerfile

COPY ext-xdebug.ini /etc/php/8.3/cli/conf.d/ext-xdebug.ini

6. Rebuild the Sail containers to apply the Xdebug configuration

sail build --no-cache

7. Install the PHP Debug extension in Visual Studio Code 8. Configure Xdebug in Visual Studio Code

.vscode/launch.json

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "log": false,
    "externalConsole": false,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}",
    },
    "ignore": [
        "**/vendor/**/*.php",
    ],
}

9. Check if Xdebug is working correctly