Skip to content

Using XDebug

Context

In case you want to develop WissKI (be it on a production site or the devcontainer) you want to use a debugger instead of using Print debugging. One proper debugging tool for drupal (and php in general) is XDebug. In the following we will describe how to setup an xdebug client on the command line and in visual studio code, and use it to debug WissKI code.

Goals

  • Configure the XDebug module on your WissKI installation
  • Configure the command line XDebug Client
  • Configure the XDebug plugin on your Visual Studio Code installation
  • Debugging a web browser request, an api request, or a drush execution

Prerequisites

  • An existing WissKI installation and access to the php configuration.
  • To run the vscode client: Visual Studio Code running on the Server, for example using Remote SSH Development or the Devcontainer.
  • To run the command-line client: Shell access to the Wisski Server.

Overview

To use xdebug you need both the xdebug php module, as well as a debugging client. To start an actual debugging session, you first need to start your chosen client and then trigger a request to connect to the client.

In the following, we will:

  1. Install the xdebug php module
  2. Configure and start the vscode client
  3. Configure and start the command line client
  4. Trigger WissKI to connect to the client

Installing, enabling and configuring the XDebug module on your WissKI installation

Note

If you are using the devcontainer, you can skip this step. Xdebug is already pre-installed and pre-configured.

First you should install, enable, and configure the XDebug Module on your WissKI installation. This depends on which installation method you used, and you might want to follow the official installation documentation. This will usually consist of two steps:

  • download and possibly compile the xdebug module; and then
  • modify the php configuration's ini files

There are many possible ways to configure xdebug. For the purposes of this document we assume the following configuration:

; set xdebug to only start when a "trigger" is present
xdebug.mode=debug
xdebug.start_with_request=trigger

; expect the client to run on 127.0.0.1:9003.
; this is the standard port.
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

; these two lines are technically optional
xdebug.log=/var/log/xdebug.log
xdebug.idekey=VSCODE

Configure and start the Visual Studio Code Client

Note

In the devcontainer this is already pre-configured and you do not need to setup anything.

To configure the vscode debugging client simply install the PHP Debug extension. Then add a new debugging configuration by executing the "Debug: Add configuration" command. Either Chose "PHP: Listen for XDebug" or manually enter the following:

{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003
}

To actually start the Xdebug vscode client, go to the "Run and Debug" pane, select the created "Listen for Xdebug" configuration, and click the green run button. You can now set breakpoints using the standard vscode interface. Once you trigger a request to connect to the client (see sections below), you can use the debugging interface as you would any other vscode project.

Configure and start the xdebug command line client

To configure and start the xdebug command line client, first download the appropriate "Command Line Debug Client" dbgpClient binary from the official xdebug website. For example:

curl https://xdebug.org/files/binaries/dbgpClient -o dbgpClient
chmod +x dbgpClient
./dbgpClient

Refer to the documentation of dbgpClient on how to use it.

Triggering WissKI to connect to an XDebug client

Depending on what kind of code you wish to debug, you have to inform WissKI to connect to the running xdebug client. This is generally achieved by setting a cookie or environment variable with the value XDEBUG_TRIGGER=1. We will give three examples below, but you can always refer to the official step debugging documentation, specifically the Initiation methods.

Debugging a browser request

Install one of the official browser extensions and use it's UI to trigger a connection to xdebug.

Except from the official documentation:

The extensions are:

Each extension adds an icon to your browser where you can select which functionality you want to trigger. Xdebug will continue to start debugging for every request as long as the debug toggle has been enabled.

Debugging a command-line script or tool

To run a script or php command, you only need to set the XDEBUG_TRIGGER environment variable. For example:

XDEBUG_TRIGGER=1 php my-script.php

Or to invoke a command-line tool, such as phpunit:

XDEBUG_TRIGGER=1 phpunit .

Warning

Drush is special, as it disables XDebug by default. To run a drush command, you need to explicitly re-enable it by passing the global --xdebug flag. You then also need to set the environment variable. For example, to debug the list pathbuilders drush command:

XDEBUG_TRIGGER=1 drush --xdebug wisski-core:list-pathbuilders

Debugging an API request

You need to set the XDEBUG_TRIGGER=1 cookie on your HTTP request. For example when invoking an API request via curl:

curl  --cookie XDEBUG_TRIGGER=1 https://example.wiss-ki.eu/wisski/api/v0/pathbuilder/list