Upgrading from Xdebug 2 to 3

English 日本語

An upgrade guide detailing which changes there are between Xdebug 2 and 3, and how to reconfigure your set-up to do similar things.

New Concepts #

Unlike Xdebug 2, where there was an enabling setting for each feature, with Xdebug 3 you put Xdebug into a specific mode, which can be configured with the xdebug.mode setting.

This setting, in combination with xdebug.start_with_request is the new way to enable functionality, and to configure when Xdebug's feature activates.

The idea behind this is that it is important that Xdebug only has overhead for the features that are actually wanted. For example, it makes no sense have both Profiling and Step Debugging active at the same time.

Besides setting the mode with xdebug.mode, you can also set the mode with the XDEBUG_MODE environment variable. If this environment variable is active, it overrides the mode as set through xdebug.mode.

Note that the mode must be set when the PHP process starts, so unlike the settings in Xdebug 2 which it replaces, you can not set it in configuration files which are loaded on each request such as .htaccess or .user.ini.

To make sure that just Step Debugging is enabled, instead of:

xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.profiler_enable=0
xdebug.auto_trace=0
xdebug.coverage_enable=0

You now only do:

xdebug.mode=debug

Or, on the command line:

export XDEBUG_MODE=debug
php script-name.php

You can use the new xdebug_info() function to see what Xdebug's configuration is. Its output will also include other diagnostic information with regards to debug connection attempts and file permissions.

Step Debugging #

Xdebug's default debugging port has changed from 9000 to 9003.

Activating on the Command Line

Instead of setting the XDEBUG_CONFIG environment variable to idekey=yourname, you must set XDEBUG_SESSION to yourname:

export XDEBUG_SESSION=xdebug_is_great

Automatically Starting the Debugger

The xdebug.remote_autostart setting has been removed. Instead, set xdebug.start_with_request to yes.

Starting the Debugger During a Request

In Xdebug 3 calling xdebug_break() will only initiate a debugging session when xdebug.start_with_request is set to trigger.

It will no longer trigger a debugging session when xdebug.start_upon_error=yes (the replacement for Xdebug 2's xdebug.remote_mode=jit).

A debug session will be initiated upon a PHP Notice or Warning, or when a Throwable is thrown, when xdebug.start_upon_error is set to yes, regardless of what the value for xdebug.start_with_request is.

Changed Function Behaviour #

xdebug_break()

This function will no longer initiate a debugging session when xdebug.start_upon_error is set to yes (the replacement for Xdebug 2's xdebug.remote_mode=jit).

It will still initate a debugging request when xdebug.start_with_request is set to trigger.

Changed Configuration Settings #

Xdebug 3 has removed and changed a lot of configuration settings. This section lists the removed settings and their replacements.

xdebug.auto_trace #

Use xdebug.mode=trace with xdebug.start_with_request=yes.

xdebug.collect_includes #

Has been removed. File names for include() and require() are now always included in Development Helpers and Function Trace output.

xdebug.collect_params #

Has been removed. Arguments are now always visible with variable contents and argument name in Development Helpers and Function Trace output.

xdebug.collect_vars #

Has been removed, it was only used in combination with the xdebug_get_declared_vars() function, which has also been removed.

xdebug.coverage_enable #

Use xdebug.mode=coverage.

xdebug.default_enable #

Use xdebug.mode=develop.

xdebug.extended_info #

No replacement. Xdebug turns on this PHP engine setting automatically when needed.

xdebug.gc_stats_enable #

Use xdebug.mode=gcstats.

xdebug.gc_stats_output_dir #

Use the generic xdebug.output_dir setting.

xdebug.overload_var_dump #

Has been removed. PHP's var_dump() is now always overloaded through xdebug_var_dump() when xdebug.mode is set to develop. The xdebug_var_dump() function is available independent of which mode is configured.

xdebug.profiler_enable #

Use xdebug.mode=profile.

xdebug.profiler_enable_trigger #

Use xdebug.mode=profile with xdebug.start_with_request=trigger.

xdebug.profiler_enable_trigger_value #

Use the generic xdebug.trigger_value setting.

xdebug.profiler_output_dir #

Use the generic xdebug.output_dir setting.

xdebug.remote_addr_header #

Replaced by xdebug.client_discovery_header.

xdebug.remote_autostart #

Use xdebug.mode=debug with xdebug.start_with_request=yes.

xdebug.remote_connect_back #

Replaced by xdebug.discover_client_host.

xdebug.remote_enable #

Use xdebug.mode=debug.

xdebug.remote_handler #

No replacement. Xdebug's step debugger only supported the DBGp handler.

xdebug.remote_host #

Replaced by xdebug.client_host.

xdebug.remote_log #

Replaced by xdebug.log, which also includes log messages beyond Step Debugging.

xdebug.remote_log_level #

Replaced by xdebug.log_level.

xdebug.remote_mode #

For the req value (the original default), use xdebug.mode=debug with xdebug.start_with_request=trigger. If the original xdebug.remote_autostart behaviour is necessary, use xdebug.start_with_request=yes instead of trigger.

For the jit value, use xdebug.mode=debug and xdebug.start_upon_error=yes.

xdebug.remote_port #

Replaced by xdebug.client_port.

The default value has also changed from 9000 to 9003.

xdebug.remote_timeout #

Replaced by xdebug.connect_timeout_ms.

xdebug.show_mem_delta #

Has been removed. The difference in memory usage can be calculated by comparing the usage in the current frame with the previous one.

xdebug.trace_output_dir #

Use the generic xdebug.output_dir setting.

xdebug.trace_enable_trigger #

Use xdebug.mode=trace with xdebug.start_with_request=trigger.

xdebug.trace_enable_trigger_value #

Use the generic xdebug.trigger_value setting.

Changes to Functions #

xdebug_disable()

Has been removed.

To prevent Xdebug from showing stack traces, do not configure Xdebug's develop mode in xdebug.mode, or turn off PHP's html_errors INI setting.

xdebug_enable()

Has been removed.

To configure Xdebug to showing stack traces, include develop in xdebug.mode.

xdebug_get_declared_vars()

Has been removed.

The information that this function returned can be obtained through the xdebug_get_function_stack() function.

xdebug_is_enabled()

Has been removed, but was never originally documented or supported.

Changed Constants #

The following constants have been changed:

XDEBUG_PATH_WHITELIST: Is now: XDEBUG_PATH_INCLUDE
XDEBUG_PATH_BLACKLIST: Is now: XDEBUG_PATH_EXCLUDE
XDEBUG_NAMESPACE_WHITELIST: Is now: XDEBUG_NAMESPACE_INCLUDE
XDEBUG_NAMESPACE_BLACKLIST: Is now: XDEBUG_NAMESPACE_EXCLUDE