How to set up XDebug with VSCode in a Laravel Sail environment

If you’re working on a Laravel project with Sail and want to debug your code using VSCode, setting up Xdebug is a great way to streamline your development workflow. In this guide, we’ll walk through all the steps you need to get Xdebug up and running.

1. Update Your .env File

First, open your project’s .env file and add the following line:

SAIL_XDEBUG_MODE=develop,debug,coverage

What this does:

Enables Xdebug in develop, debug, and coverage modes within the Sail environment. This gives you all the necessary tools for an effective debugging session.

2. Adjust docker-compose.yml

Next, you’ll need to update the docker-compose.yml file to ensure your custom PHP configuration (including Xdebug) is applied inside the container. Add the following volume mapping under the main application service:

- './docker/8.3/php.ini:/etc/php/8.3/cli/conf.d/99-sail.ini'

Context:

Here’s how your services section might look (don’t change existing lines, just add the above mapping):

services:
    laravel.test:
        build:
            context: './docker/8.3'
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: 'sail-8.3/app'
        extra_hosts:
            - 'host.docker.internal:host-gateway'
        ports:
            - '${APP_PORT:-80}:80'
            - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
            IGNITION_LOCAL_SITES_PATH: '${PWD}'
        volumes:
            - '.:/var/www/html'
            - './docker/8.3/php.ini:/etc/php/8.3/cli/conf.d/99-sail.ini'
        networks:
            - sail
        depends_on:
            - mysql

3. Publish Sail’s Configuration

Run the following Artisan command:

sail artisan sail:publish

Why?

This publishes Sail’s configuration files to your project, allowing you to customize them if you need to tweak the environment further.

4. Configure Xdebug in docker/8.3/php.ini

Open docker/8.3/php.ini and add these lines:

[XDebug]
xdebug.mode=${XDEBUG_MODE}
xdebug.start_with_request = yes

What this does:

• xdebug.mode=${XDEBUG_MODE} ensures the mode is pulled from your .env file.
• xdebug.start_with_request = yes means a debug session starts automatically with every HTTP request, so you won’t have to manually trigger it.

5. Update Your VSCode Debug Configuration

In your .vscode/launch.json, modify or add a debug configuration block like this:

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
    },
    "hostname": "localhost"
}

Explanation:

• Port 9003 is the default for Xdebug 3.
• pathMappings maps the container’s /var/www/html directory to your local project directory (the ${workspaceFolder}), ensuring breakpoints align correctly with the code running in Docker.

Summary of the Steps

1. Add SAIL_XDEBUG_MODE=develop,debug,coverage to .env.
2. Update docker-compose.yml to include the volume mapping for php.ini.
3. Run sail artisan sail:publish.
4. Add the Xdebug configuration to docker/8.3/php.ini.
5. Update your VSCode debug configuration to listen on port 9003.

Following these steps should allow Xdebug to connect to VSCode, making it easy to step through code, inspect variables, and troubleshoot issues in your Laravel app under Sail.

Additional Tips

• After making changes, you might need to rebuild the containers:

  sail build --no-cache
  sail up -d

• Consider using a browser extension like Xdebug Helper for Chrome or Firefox.
  • For Firefox or Chrome, set the XDEBUG_VSCODE as the IDE key in the extension settings.

These optional steps can help you toggle debugging sessions on and off more easily.

---

With these configurations, you’re ready to debug your Laravel application running in a Sail environment directly from VSCode!