Skip to content
Devilbox

Docker on Windows: Xdebug for Sublime Text 3

orphan

Docker on Windows: Xdebug for Sublime Text

Use this guide to debug Devilbox projects with Sublime Text 4, the xdebug-client package, PHP 8.3 or 8.4, Xdebug 3, and Docker Desktop on Windows.

Prerequisites

  • A running Devilbox checkout on Windows.
  • Docker Desktop for Windows with Linux containers enabled.
  • Sublime Text 4 with Package Control installed.
  • The xdebug-client package installed from Package Control.

See also: Xdebug options explained.

Assumptions

SettingExample
Devilbox directoryC:\Users\cytopia\repo\devilbox
Local project pathC:\Users\cytopia\repo\devilbox\data\www\myapp
Container project path/shared/httpd/myapp
PHP version8.4
Xdebug client hosthost.docker.internal
Xdebug client port9003

The local project path is where Sublime opens your files. The container path is what PHP reports to the debug client.

Configure Sublime Text 4

  1. Install xdebug-client with Package Control.
  2. Open Preferences | Package Settings | Xdebug Client | Settings.
  3. Configure the listener and path mapping for your project.
{
  "path_mapping": {
    "/shared/httpd/myapp": "C:\\Users\\cytopia\\repo\\devilbox\\data\\www\\myapp"
  },
  "url": "http://myapp.lvh.me/",
  "ide_key": "sublime.xdebug",
  "host": "0.0.0.0",
  "port": 9003
}

Start the Sublime debug listener before loading the page in your browser.

Configure Xdebug 3

Create cfg/php-ini-8.4/xdebug.ini in your Devilbox checkout. Use cfg/php-ini-8.3/xdebug.ini if your project runs on PHP 8.3.

Terminal window
host> cd C:\Users\cytopia\repo\devilbox
host> notepad cfg\php-ini-8.4\xdebug.ini

Add the current Xdebug 3 settings:

zend_extension=xdebug.so


xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey=sublime.xdebug


; Optional, useful while testing connections
xdebug.log=/var/log/php/xdebug.log

Restart Devilbox

Restart the PHP container so the new ini file is loaded:

Terminal window
host> cd C:\Users\cytopia\repo\devilbox
host> docker-compose stop php
host> docker-compose rm -f php
host> docker-compose up php httpd bind

Open your project URL with the Sublime listener active. Sublime should stop at breakpoints once the path mapping matches the container path.