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 either2
or3
. - (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 either2
or3
. - Otherwise, it checks if in the currently loaded configuration the environment variable
RIPTIDE_XDEBUG_VERSION
is set to either2
or3
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:
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:
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.
The debugger should now work for this project.