Skip to content

Configure and Use XDebug

Jump to bottom
Christoph Kluge edited this page Sep 10, 2021 · 3 revisions

Using XDebug with cc-docker and Virtual Studio Code (VSCode)

The cc-php container can be built with XDebug (Version 3.0.4), which allows step debugging using a supported IDE or editor. In this Wiki, we will use VSCode.

Configuration in cc-docker

Prerequisites

Activate the install of XDebug within the cc-php container by setting PHP_XDEBUG_INIT to true within the .env file.

The second prerequisite is to determine the hosts IP address for XDebug to communicate successfully.

  • MAC, Windows: Use host.internal.docker (Resolves host IP from within docker automatically).
  • Linux: Check output of ifconfig, then use IP displayed on adapter docker0 (e.g. inet X.X.X.X).

Note: Other adapters' IP addresses also work, as long as they describe the host running the docker stack.

Should Xdebug not connect to your IDE correctly, try using docker0's IP also on MAC/Windows.

Settings (Docker on localhost)

XDebug options are configured via \.env in the PHP section.

  • PHP_XDEBUG_INIT; Default value: false
  • PHP_XDEBUG_MODE; Default value: debug,develop
  • PHP_XDEBUG_CLIENT_PORT; Default value: 9003 (For XDebug Version 3 and up)
  • PHP_XDEBUG_CLIENT_HOST; Default value: host.docker.internal (MAC and Windows only, for Linux see above)

XDebug is otherwise preconfigured to use "step debugging".

Configuration in VSCode

Prerequisites

VSCode offers a marketplace for extensions, from which the following package needs to be installed

Settings (Docker on localhost)

  • In the Debugger-Tab, create a new config launch.json for PHP
  • Configure the Listen for Xdebug section as follows:
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "hostname": "localhost",
            "port": 9003,
            "log": false,
            // Mappings:: Server : Local
            "pathMappings": {
                "/var/www/symfony": "${workspaceFolder}/data/symfony"
            }
        }
    ]
  • When running on Linux, exchange "hostname": "localhost" with "hostname": "YOUR_IP", using the IP determined from ifconfig.

Start listening in VSCode

  • Build all cc-docker containers.
  • Open VSCode
  • Start listening for Xdebug for the cc-docker project by launching the debugger in the according tab (Green "Play" symbol).

The VSCode debugger now listens on port 9003 for incoming Xdebug information.

  • Start the cc-docker container stack.

During container startup, the VSCode window should be focused by your OS, displaying the first breakpoint within the according file.

  • With the VSCode control interface, you can now step through indicated code parts.

Clone this wiki locally