PHP Debugging with XDebug

By default XDebug is disabled when using PHP projects, for performance reasons.

If you want to enable XDebug, make sure you have the riptide-plugin-php-xdebug package installed. This is installed by default since Riptide 0.5.0.

See Status of XDebug

To see if XDebug is currently enabled for a project, use the following command:

$ riptide xdebug
Xdebug status for riptidedocs: Disabled.
Detected Xdebug version: 3
Mode: debug
Extra configuration:
Request trigger: no (xdebug.start_with_request=yes)

Enable / Disable XDebug

Use the following commands to toggle XDebug for all running services and all Riptide commands for a single project:

$ riptide xdebug off
$ riptide xdebug on

Xdebug Mode

By default Xdebug is configured to run in “develop” mode. Using the -m/--mode option you can change the mode Xdebug should use. You can comma-seperate multiple modes.

This setting only applies to Xdebug 3.

Activation method

By default xdebug.start_with_request is set to yes, so the only triggers configuring whether or not debugging should happen are this command and your IDE listening for connections or not.

If you want, you can use --request/-r to set this value to trigger. The debugger will then only connect if it detects the cookie for it (see Xdebug documentation). To disable this again use --no-request/-R.

This setting only applies to Xdebug 3.

Additional configuration

You can pass additional configuration as comma-seperated key-value pairs using the option --config/-c. This is the same format as used by the XDEBUG_CONFIG environment variable.

For example, to set the xdebug.log and xdebug.log_level settings:

riptide xdebug -c ‘log=/tmp/xdebug.log,log_level=10’ on

Xdebug Version

The plugin tries to automatically detect the Xdebug version. For this it tries the following:

  • First it checks if the environment variable (that Riptide is running with!) RIPTIDE_XDEBUG_VERSION is set to either 2 or 3.
  • (RECOMMENDED) Otherwise it checks if the label php_xdebug_version of the image assigned to the first service in the app with the role php` is set to either 2 or 3.
  • Otherwise, it checks if in the currently loaded configuration the environment variable RIPTIDE_XDEBUG_VERSION is set to either 2 or 3 at ANY service or comamnd in the app (absolutely not recommended).

Based on the determined value, it will set the correct Xdebug configuration. If no version could be detected, Riptide will assume version 2 and output a warning.

Enable XDebug in PHPStorm

When XDebug is enabled, it will automatically try to connect.

Enable Remote Debugging in PHPStorm to accept debugging connections:

../_images/xdebug_1.png

When a service container tries to connect for the first time, you have to configure path mappings. You will see the following warning in the debugging window of PhpStorm:

../_images/xdebug_2.png

Click on “Configure Server”. Create a new server entry and as a “Name” enter the name that was shown in the previous warning (in this case riptide-demo-xdebug). As “Host” enter the URL of the project/service.

Check “Use path mappings”. Select the sub-directory your src entry of your riptide.yml points to. In this example src is ., so we will select the top project directory. Enter /src as “Absolute Path on the server” and save.

../_images/xdebug_3.png

The debugger should now work for this project.