Upgrading from Xdebug 2 to 3

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.

To make sure that just Step Debugging is active, 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

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 Aids and Function Trace output.

xdebug.collect_params

Has been removed. Arguments are now always visible with variable contents and argument name in Development Aids 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