Enable Xdebug¶

This tutorial shows you how to enable and use Xdebug with the Devilbox.

Enable Xdebug ¶

This section shows you the minimum required *.ini ini settings to get xdebug to work with the Devilbox. It will also highlight the differences between operating system and Docker versions.

Required for all OS ¶

Additionally to the specific configurations for each operating system and Docker version you will probably also want to add the following to your ini file:

xdebug.ini¶

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_port=9000
xdebug.remote_autostart=1
xdebug.idekey="PHPSTORM"
xdebug.remote_log=/var/log/php/xdebug.log

default_enable ¶

By enabling this, stacktraces will be shown by default on an error event. It is advisable to leave this setting set to 1.

This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.

remote_handler ¶

Can be either 'php3' which selects the old PHP 3 style debugger output, 'gdb' which enables the GDB like debugger interface or 'dbgp' - the debugger protocol. The DBGp protocol is the only supported protocol.

Note: Xdebug 2.1 and later only support 'dbgp' as protocol.

remote_port ¶

The port to which Xdebug tries to connect on the remote host. Port 9000 is the default for both the client and the bundled debugclient. As many clients use this port number, it is best to leave this setting unchanged.

remote_autostart ¶

Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see Remote Debugging). When this setting is set to 1, Xdebug will always attempt to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE variable was not present.

idekey ¶

Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last USERNAME. The default is set to the first environment variable that is found. If none could be found the setting has as default ‘’. If this setting is set, it always overrides the environment variables.

For the sake of this tutorial we are going to use PHPSTORM as an example value.

remote_log ¶

Keep the exact path of /var/log/php/xdebug.log. You will then have the log file available in the Devilbox log directory of the PHP version for which you have configured Xdebug.

Important

You can set the value of xdebug.idekey to whatever you like, however it is important to remember what value you have set. Throughout the examples in this tutorial it is assumed, that the value is PHPSTORM.

Linux ¶

xdebug.ini¶

xdebug.remote_connect_back=1

MacOS (Docker for Mac)¶

Docker 18.03.0-ce+ and Docker compose 1.20.1+

xdebug.ini¶

xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0

Docker 17.12.0-ce+ and Docker compose 1.18.0+

xdebug.ini¶

xdebug.remote_host=docker.for.mac.host.internal
xdebug.remote_connect_back=0

Docker 17.06.0-ce+ and Docker compose 1.14.0+

xdebug.ini¶

xdebug.remote_host=docker.for.mac.localhost
xdebug.remote_connect_back=0

If you have older versions, upgrade.

MacOS (Docker Toolbox)¶

Warning

This is a legacy solution, upgrade to Docker for Mac https://docs.docker.com/toolbox

Windows (Docker for Windows)¶

Docker 18.03.0-ce+ and Docker compose 1.20.1+

xdebug.ini¶

xdebug.remote_host=docker.for.win.host.internal
xdebug.remote_connect_back=0

Docker 17.06.0-ce+ and Docker compose 1.14.0+

xdebug.ini¶

xdebug.remote_host=docker.for.win.host.localhost
xdebug.remote_connect_back=0

If you have older versions, upgrade.

Windows (Docker Toolbox)¶

Warning

This is a legacy solution, upgrade to Docker for Windows https://docs.docker.com/toolbox

Configure your IDE ¶

Required for all IDE ¶

Path mapping ¶

The path mapping is a mapping between the file path on your host operating system and the one inside the PHP Docker container.

The path on your host operating system is the one you have set in HOST_PATH_HTTPD_DATADIR. In case you have set a relative path in .env, ensure to retrieve the absolute path of it when setting up your IDE config.

The path inside the PHP Docker container is always /shared/httpd.

Important

Even though your path in .env for HOST_PATH_HTTPD_DATADIR might be relative (e.g. ./data/www), you need to get the actualy absolute path of it, when setting up your IDE.

Install php-debug
Configure config.cson (File -> Config…)
Adjust your xdebug.ini

For Atom, you need to provide a different xdebug.idekey in your php.ini file xdebug.ini:

xdebug.ini¶

xdebug.idekey=xdebug.atom

Linux ¶

launch.json¶

"php-debug":
 {
   ServerPort: 9000
   PathMaps: [
     "remotepath;localpath"
     "/shared/httpd;/home/cytopia/repo/devilbox/data/www"
   ]
 }

Set DBGp proxy settings:

Install Xdebug Client via the Sublime Package Control.
Configure Xdebug.sublime-settings (Tools -> Xdebug -> Settings - User)

Linux ¶

Xdebug-sublime-settings¶

{
    "path_mapping": {
        "/shared/httpd" : "/home/cytopia/repo/devilbox/data/www"
    },
    "url": "",
    "ide_key": "PHPSTORM",
    "host": "0.0.0.0",
    "port": 9000
}

Install vscode-php-debug
Configure launch.json

Linux ¶

launch.json¶

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xbebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "serverSourceRoot": "/shared/httpd",
            "localSourceRoot": "/home/cytopia/repo/devilbox/data/www"
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}