If you find Xdebug useful, please consider supporting the project.

Upgrading from Xdebug 2 to 3

An upgade 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.

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

Step Debugging

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

xdebug.coverage_enable

Use xdebug.mode=coverage.

xdebug.default_enable

Use xdebug.mode=display.

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_autostart

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

xdebug.remote_enable

Use xdebug.mode=debug.

xdebug.remote_handler

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

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.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.

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