Debugging Docker with Xdebug

If you're running the Scratchpads Docker container and need to investigate the code for bugs or errors, you can set up Xdebug.

Xdebug is already installed on the Scratchpads Docker containers. To enable it, you need to edit your .env file. This will be different depending on whether your host machine is running Linux or not.

For Linux users, make sure your .env file contains these three lines:

APACHE_PHP_XDEBUG_REMOTE_ENABLE=1
APACHE_PHP_XDEBUG_REMOTE_HOST=172.17.0.1
APACHE_PHP_XDEBUG_REMOTE_AUTOSTART=1

Here, 172.17.0.1 is the host machine's IP address on the Docker network. By default this is always 172.17.0.1 for Linux (you can check this by running ifconfig and looking for the docker0 interface).

For Windows or Mac users, you should have these lines:

APACHE_PHP_XDEBUG_REMOTE_ENABLE=1
APACHE_PHP_XDEBUG_REMOTE_HOST=host.docker.internal
APACHE_PHP_XDEBUG_REMOTE_AUTOSTART=1

In either case, you must restart your docker containers to apply these changes:

docker-compose down
docker-compose up -d

Now install an Xdebug client on your host machine.

Visual Studio

If you're using Visual studio, you can install the Xdebug plugin.

Once it's installed, you can configure it for Scratchpads. Go to Run > Open Configurations and make sure it looks something like this:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}",
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

The important parts here are port and pathMappings.

Now when you start debugging (press F5) and visit http://localhost your debugger should break on any breakpoints. If you want to break on errors, add a breakpoint in the _drupal_log_error function in errors.inc.