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'sxdebug.remote_mode=jit
).It will still initate a debugging request when xdebug.start_with_request is set to
trigger
. xdebug.auto_trace
Use xdebug.mode=
trace
with xdebug.start_with_request=yes
.xdebug.collect_includes
Has been removed. File names for
include()
andrequire()
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() whenxdebug.mode
is set todevelop
. 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 originalxdebug.remote_autostart
behaviour is necessary, use xdebug.start_with_request=yes
instead oftrigger
.For the
jit
value, use xdebug.mode=debug
and xdebug.start_upon_error=yes
. xdebug.remote_port
-
Replaced by xdebug.client_port.
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.
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'shtml_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.
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
Changed Configuration Settings
Xdebug 3 has removed and changed a lot of configuration settings. This section lists the removed settings and their replacements.
Changes to Functions
Changed Constants
The following constants have been changed: