Tuesday, June 3, 2025How to enable Xdebug in Laravel Sail

Keven Client A. Cataluña @LinkedIn

Tags

Docker Laravel PHP Xdebug Visual Studio Code

Previous postDockerize Laravel with Sail

Next postSetup PHP development environment with Docker

← Back to the posts

Introduction

This guide explains how to enable Xdebug in Laravel Sail for efficient PHP debugging, including configuring the .env file, publishing Docker files, modifying the container setup, and setting up Visual Studio Code for debugging.

Steps1. 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

Keven Client A. Cataluña @LinkedIn