Added xdebug 3.0 to the project using xdebugs built-in env vars.

[nhaynes]

I'm aware that this has been attempted in previous PRs that have been denied but I thought I'd take another chance as I believe my implementation has a rather small footprint and may be more palatable to the maintainers of this repository.

I do understand their desire to keep this project lean but I have a hard time understanding how a step debugger isn't included in any basic local development environment.

Implementation

This installs Xdebug 3.0 using the php7.4 and php8.0 packages and relies on the two built in env vars already provided by xdebug: XDEBUG_MODE and XDEBUG_CONFIG to control and configure the extension. These are mapped directly to SAIL_XDEBUG_MODE and SAIL_XDEBUG_CONFIG that can be controlled in the projects .env file.

Configuraiton

XDEBUG_MODE is set to off by default. To enable xdebug you simply need to set the appropriate mode when starting your containers:

SAIL_XDEBUG_MODE=develop,debug

XDEBUG_CONFIG is set to client_host=host.docker.internal by default so it will be properly configured out of the box to work on Mac and Windows.

Since host.docker.internal isn't available in containers running on Linux hosts, Linux users need to update this env var in their projects:

SAIL_XDEBUG_CONFIG="client_host=<host-ip-address>"

They can get the host ip address by running the following command:

docker inspect -f {{range.NetworkSettings.Networks}}{{.Gateway}}{{end}} <container-name>

CLI Usage

I added a sail debug command that can be used to start a debugging session when running an artisan command:

# Without xdebug:
sail artisan foo:bar

# With xdebug:
sail debug foo:bar

# Without xdebug:
sail test

# With xdebug:
sail debug test

Browser Usage

If you want to debug a web session, follow the instructions provided by xdebug for initiating an xdebug session from the web browser.

Browser Extensions

Current Issue

There is currently an issue with the serve command that prevents xdebug configured via env variables from working with the built-in webserver but I've included a PR to laravel/framework to alleviate this: laravel/framework#38211

Once that is merged in we can fix this issue by overriding the env vars that are passed thru to the built-in webserver:

$this->app->singleton('command.serve', function() {
        return new ServeCommand([
                'APP_ENV',
                'LARAVEL_SAIL',
                'PHP_CLI_SERVER_WORKERS',
                'XDEBUG_MODE',
                'XDEBUG_CONFIG',
        ]);
});

[taylorotwell]

Can you make a PR on the env var issue with the explicit env variables we need?

[nhaynes]

@taylorotwell here is the new PR for those env vars: laravel/framework#38228

Thanks!

[abbluiz]

@nhaynes In Linux, this IP changes each time I close/open the container

[nhaynes]

@nhaynes In Linux, this IP changes each time I close/open the container

Interesting...this should only happen if the network is getting recreated each time. Are you running sail down -v by chance? This would destroy the volumes and networks as well as the containers.

Usually, once you run sail up -d once, the volumes and networks remain and the IP stays the same.

Or have you customized the network configured in docker-compose.yml in any way?

[abbluiz]

@nhaynes sail down removes the network for some reason. Is there something wrong with my docker-compose.yml? I just removed the other services from it:

# For more information: https://laravel.com/docs/sail
version: '3'
services:
    laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/8.0
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.0/app
        ports:
            - '${APP_PORT:-80}:80'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
            XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
            XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
        depends_on:
            - mariadb
    mariadb:
        image: 'mariadb:10'
        ports:
            - '${FORWARD_DB_PORT:-3306}:3306'
        environment:
            MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
            MYSQL_DATABASE: '${DB_DATABASE}'
            MYSQL_USER: '${DB_USERNAME}'
            MYSQL_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ALLOW_EMPTY_PASSWORD: 'yes'
        volumes:
            - 'sailmariadb:/var/lib/mysql'
        networks:
            - sail
        healthcheck:
          test: ["CMD", "mysqladmin", "ping", "-p${DB_PASSWORD}"]
          retries: 3
          timeout: 5s
networks:
    sail:
        driver: bridge
volumes:
    sailmariadb:
        driver: local

[abbluiz]

Never mind, I don't need to run sail down every time