GeezerVisonThe World Wide Web, restored to 800 pixels of glory. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Home|About|Gaming cabinet|Archives|How it works|Starter sites | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GeezerVison is showing xdebug.org — Xdebug: Documentation » All settings Documentation - all settingsThis section describes all available configuration settings available in Xdebug.
Unless specifically mentioned, each setting can be set in
XDEBUG_CONFIG environment variable #
A select set of settings can be set through an export XDEBUG_CONFIG="client_host=192.168.42.34 log=/tmp/xdebug.log"
The documentation for each setting below will indicate if it can be set through
Some web servers have a configuration option to
prevent environment variables from being propagated to PHP and Xdebug.
integer xdebug.cli_color = 0 #If this setting is 1, Xdebug will color var_dumps and stack traces output when in CLI mode and when the output is a tty. On Windows, the ANSICON tool needs to be installed. If the setting is 2, then Xdebug will always color var_dumps and stack trace, no matter whether it's connected to a tty or whether ANSICON is installed. In this case, you might end up seeing escape codes. See this article for some more information. This setting can additionally be configured through the
string xdebug.client_discovery_header = "HTTP_X_FORWARDED_FOR,REMOTE_ADDR" #If xdebug.client_discovery_header is configured to be a non-empty string, then the
value is used as key in the For example, if xdebug.client_discovery_header is set to
It is possible to configure multiple fallbacks by using a comma separated
list of values. For example if you want to use PHP automatically prepends If you have logging enabled, and set the xdebug.log_level setting to
Xdebug 3.2 and later no longer fall back to the
string xdebug.client_host = localhost #Configures the IP address or hostname where Xdebug will attempt to connect to when initiating a debugging connection. This address should be the address of the machine where your IDE or debugging client is listening for incoming debugging connections. Xdebug also supports a few other ways of specifying the host to connect to,
but these methods are not always available. xdebug_info() shows whether
the
If xdebug.discover_client_host is enabled then Xdebug will only use the value of this setting in case Xdebug can not connect to an IDE using the information it obtained from HTTP headers. In that case, the value of this setting acts as a fallback only. This setting can additionally be configured through the
integer xdebug.client_port = 9003 #The port to which Xdebug tries to connect on the remote host. Port
This setting can additionally be configured through the
string xdebug.cloud_id = #With this setting you configure Xdebug for use with Xdebug Cloud. It needs to match one of the tokens from your profile page. Your IDE needs to be configured with the same token for Xdebug and your IDE to communicate through Xdebug Cloud. In PhpStorm you can find this setting under: boolean xdebug.collect_assignments = false #This setting, defaulting to 0, controls whether Xdebug should add
variable assignments to function traces. Assign-by-var ( boolean xdebug.collect_params = true #Introduced in Xdebug >= 3.3 If enabled (default), files created with the Function Trace feature will include all arguments to functions and methods. When disabled, the argument to each function and method will not be present in the trace files. boolean xdebug.collect_return = false #This setting, defaulting to 0, controls whether Xdebug should write the return value of function calls to the trace files. integer xdebug.connect_timeout_ms = 200 #The amount of time in milliseconds that Xdebug will wait for on an IDE to acknowledge an incoming debugging connection. The default value of 200 ms should in most cases be enough. In case you often get dropped debugging requests, perhaps because you have a high latency network, or a development box far away from your IDE, or have a slow firewall, then you can should increase this value. Please note that increasing this value might mean that your requests seem to 'hang' in case Xdebug tries to establish a connection, but your IDE is not listening. string xdebug.control_socket = "default" #Introduced in Xdebug >= 3.3 Linux and Windows only. When set to A command can currently be used to:
You should use the Xdebug Control tool to interact with this control socket. When this setting is set to
If your system (or container) does not have a reliable TSC clock, then
You can programatically check whether control sockets are enabled for your PHP
build by calling xdebug_info() with boolean xdebug.discover_client_host = false #If enabled, Xdebug will first try to connect to the client that made the
HTTP request. It checks the If xdebug.client_discovery_header is configured, then the If Xdebug can not connect to a debugging client as found in one of the HTTP headers, it will fall back to the hostname or IP address as configured by the xdebug.client_host setting. This setting does not apply for debugging through the CLI, as the
This setting can additionally be configured through the
Please note that there is no filter available, and anybody who can connect to the webserver will then be able to start a debugging session, even if their address does not match xdebug.client_host. string xdebug.dump.* = Empty #* can be any of COOKIE, FILES, GET, POST, REQUEST, SERVER, SESSION. These seven settings control which data from the superglobals is shown when an error situation occurs. Each of those php.ini setting can consist of a comma separated list of
variables from this superglobal to dump, or In order to dump the REMOTE_ADDR and the REQUEST_METHOD when an error occurs, and all GET parameters, add these settings: xdebug.dump.SERVER = REMOTE_ADDR,REQUEST_METHOD xdebug.dump.GET = * boolean xdebug.dump_globals = true #When this setting is set to boolean xdebug.dump_once = true #Controls whether the values of the superglobals should be dumped on all error situations (set to 0) or only on the first (set to 1). boolean xdebug.dump_undefined = false #If you want to dump undefined values from the superglobals you should set this setting to 1, otherwise leave it set to 0. string xdebug.file_link_format = #This setting determines the format of the links that are made in the display of stack traces where file names are used. This allows IDEs to set up a link-protocol that makes it possible to go directly to a line and file by clicking on the filenames that Xdebug shows in stack traces. An example format might look like: myide://%f@%l The possible format specifiers are:
For various IDEs/OSses there are some instructions listed on how to make this work: PhpStormIn the configuration file, add the following line, including the single quotes. This uses PhpStorm's REST API. xdebug.file_link_format='javascript: var r = new XMLHttpRequest; r.open("get", "http://localhost:63342/api/file/%f:%l");r.send()'
Firefox on Linux
Windows and Netbeans
string xdebug.filename_format = ...%s%n #This setting determines the format with which Xdebug renders
filenames in HTML stack traces (default:
The possible format specifiers are listed in this table. The example output is
rendered according to the full path
integer xdebug.force_display_errors = 0 #If this setting is set to integer xdebug.force_error_reporting = 0 #This setting is a bitmask, like error_reporting. This bitmask will be logically ORed with the bitmask represented by error_reporting to dermine which errors should be displayed. This setting can only be made in php.ini and allows you to force certain errors from being shown no matter what an application does with ini_set(). string xdebug.gc_stats_output_name = gcstats.%p #This setting determines the name of the file that is used to dump garbage collection statistics into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name. See the xdebug.trace_output_name documentation for the supported specifiers. integer xdebug.halt_level = 0 #This setting allows you to configure a mask that determines whether, and which, notices and/or warnings get converted to errors. You can configure notices and warnings that are generated by PHP, and notices and warnings that you generate yourself (by means of trigger_error()). For example, to convert the warning of strlen() (without arguments) to an error, you would do: ini_set('xdebug.halt_level', E_WARNING);
strlen();
echo "Hi!\n";
Which will then result in the showing of the error message, and the abortion
of the script. The setting is a bit mask, so to convert all notices and warnings into errors for all applications, you can set this in php.ini: xdebug.halt_level=E_WARNING|E_NOTICE|E_USER_WARNING|E_USER_NOTICE The bitmask only supports the four level that are mentioned above. string xdebug.idekey = *complex* #Controls which IDE Key Xdebug should pass on to the debugging client or proxy. The IDE Key is only important for use with the DBGp Proxy Tool, although some IDEs are incorrectly picky as to what its value is. The default is based on the If this setting is set to a non-empty string, it selects its value over
The internal IDE Key also gets updated through debugging session management and overrides the value of this setting as is explained in the Step Debugging documentation. This setting can additionally be configured through the
string xdebug.log = #Configures Xdebug's log file. Xdebug will log to this file all file creations issues, Step Debugging connection attempts, failures, and debug communication. Enable this functionality by setting the value to a absolute path. Make sure
that the system user that PHP runs at (such as The file is opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available. The log file will include any attempt that Xdebug makes to connect to an IDE: [2693358] Log opened at 2020-09-02 07:19:09.616195 [2693358] [Step Debug] INFO: Connecting to configured address/port: localhost:9003. [2693358] [Step Debug] ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port). [2693358] [Profiler] ERR: File '/foo/cachegrind.out.2693358' could not be opened. [2693358] [Profiler] WARN: /foo: No such file or directory [2693358] [Tracing] ERR: File '/foo/trace.1485761369' could not be opened. [2693358] [Tracing] WARN: /foo: No such file or directory [2693358] Log closed at 2020-09-02 07:19:09.617510 It includes the opening time ( It includes:
For Step Debugging: INFO: Connecting to configured address/port: localhost:9003. ERR: Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port). For Profiling: ERR: File '/foo/cachegrind.out.2693358' could not be opened. WARN: /foo: No such file or directory For Function Trace and Flame Graphs: ERR: File '/foo/trace.1485761369' could not be opened. WARN: /foo: No such file or directory All warnings and errors are described on the Description of errors page, with
detailed instructions on how to resolve the problem, if possible. All errors are always logged through
PHP's internal logging mechanism (configured with error_log
in Step Debugger CommunicationThe debugging log can also log the communication between Xdebug and an IDE.
This communication is in XML, and starts with the <init
xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
fileuri="file:///home/httpd/www.xdebug.org/html/router.php"
language="PHP" xdebug:language_version="7.4.11-dev"
protocol_version="1.0" appid="2693358" idekey="XDEBUG_ECLIPSE">
<engine version="3.0.0-dev"><![CDATA[Xdebug]]></engine>
<author><![CDATA[Derick Rethans]]></author>
<url><![CDATA[https://xdebug.org]]></url>
<copyright><![CDATA[Copyright (c) 2002-2020 by Derick Rethans]]></copyright>
</init>
The Beyond the <- feature_set -i 4 -n extended_properties -v 1
-> <response
xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
command="feature_set" transaction_id="4" feature="extended_properties" success="1">
</response>
<- step_into -i 9
-> <response
xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug"
command="step_into" transaction_id="9"
status="break" reason="ok">
<xdebug:message filename="file:///home/httpd/www.xdebug.org/html/router.php" lineno="3">
</xdebug:message>
</response>
You can read about DBGP - A common debugger protocol specification at its dedicated documation page. The xdebug.log_level setting controls how much information is logged. Many Linux distributions now use systemd, which
implements private tmp directories. This means that when PHP
is run through a web server or as PHP-FPM, the This setting can additionally be configured through the
integer xdebug.log_level = 7 #Configures which logging messages should be added to the log file. The log file is configured with the xdebug.log setting. The following levels are supported:
Criticals, errors, and warnings always show up in the diagnostics log that you can view by calling xdebug_info(). Criticals and errors are additionally logged through
PHP's internal logging mechanism (configured with error_log
in This setting can additionally be configured through the
integer xdebug.max_nesting_level = 512 #Controls the protection mechanism for infinite recursion protection. The value of this setting is the maximum level of nested functions that are allowed before the script will be aborted. When the maximum nesting level is reached, an "Error" exception is thrown. Before Xdebug 3.3, the default value was integer xdebug.max_stack_frames = -1 #Controls how many stack frames are shown in stack traces, both on the command line during PHP error stack traces, as well as in the browser for HTML traces. string xdebug.mode = develop #This setting controls which Xdebug features are enabled. This setting can only be set in The following values are accepted:
You can enable multiple modes at the same time by comma separating their
identifiers as value to xdebug.mode: XDEBUG_MODE environment variableYou can also set Xdebug's mode by setting the Some web servers have a configuration option to
prevent environment variables from being propagated to PHP and Xdebug.
string xdebug.output_dir = /tmp #The directory where Xdebug will write tracing, profiling, and garbage collection statistics to. This directory needs to be writable for the system user with which PHP is running. This setting can be changed in In some cases (when profiling, or when
xdebug.start_with_request= This setting can additionally be configured through the
Many Linux distributions now use systemd, which
implements private tmp directories. This means that when PHP
is run through a web server or as PHP-FPM, the integer xdebug.profiler_append = 0 #When this setting is set to 1, profiler files will not be overwritten when a new request would map to the same file (depending on the xdebug.profiler_output_name setting. Instead the file will be appended to with the new profile. string xdebug.profiler_output_name = cachegrind.out.%p #This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name. See the xdebug.trace_output_name documentation for the supported specifiers. This setting can additionally be configured through the
boolean xdebug.scream = false #If this setting is 1, then Xdebug will disable the @ (shut-up) operator so that notices, warnings and errors are no longer hidden. integer xdebug.show_error_trace = 0 #When this setting is set to 1, Xdebug will show a stack trace whenever an Error is raised - even if this Error is actually caught. integer xdebug.show_exception_trace = 0 #When this setting is set to 1, Xdebug will show a stack trace whenever an Exception or Error is raised - even if this Exception or Error is actually caught. Error 'exceptions' were introduced in PHP 7. integer xdebug.show_local_vars = 0 #When this setting is set to something != 0 Xdebug's generated stack dumps in error situations will also show all variables in the top-most scope. Beware that this might generate a lot of information, and is therefore turned off by default. string xdebug.start_upon_error = default #Step Debugging can be activated when a PHP Notice or Warning is emitted, or when a Throwable (Exception/Error) is thrown, depending on the value of this setting:
This setting is independent of xdebug.start_with_request, and therefore it is
not necessary to set xdebug.start_with_request string xdebug.start_with_request = default #Step Debugging, a Function Trace, Flame Graphs, Garbage Collection Statistics, or Profiling can be activated at the start of a PHP request. Whether this happens depends on the value of this setting:
integer xdebug.trace_format = 0 #The format of the trace file.
Fields for the computerized format, depend on the record type. Entry Line
Exit Line
Return Line
See the introduction for Function Trace for a few examples. integer xdebug.trace_options = 0 #This settings accepts a bitfield to enable options:
To combine multiple flags, you can use bitwise-OR (
string xdebug.trace_output_name = trace.%c #This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name. The '.xt' extension is always added automatically. The possible format specifiers are:
2 This one is only available for trace file names since Xdebug 2.6. 3 New in version 2.2. This one is set by Apache's mod_unique_id module string xdebug.trigger_value = "" #This setting can be used when xdebug.start_with_request is set to
In The legacy names Normally, Xdebug does not look at which value is actually used. If this setting is set to a non-empty string, then Xdebug will only trigger if the value matches the value of this setting. With the following settings: xdebug.mode=profile xdebug.start_with_request=trigger xdebug.trigger_value=StartProfileForMe Xdebug's profiler will only start when either the environment variable
From Xdebug 3.1, it is possible to configure multiple values by using a comma separated list. In that case, Xdebug will trigger if the supplied value matches any of the entries that are configured through this setting: xdebug.trigger_value=StartDebuggerForMe,StartDebuggerForYou See also:
boolean xdebug.use_compression = true #Introduced in Xdebug >= 3.1 If enabled, the Function Trace and Profiling features will create GZip compressed files as output. This reduces diskspace. If GZip compression is not supported by Xdebug, because it was not compiled in, then Xdebug will add a warning to its log and xdebug_info() diagnostics section. It is enabled by default if Xdebug has GZip support, and disable if Xdebug does not have GZip support. The QCacheGrind tool that you can use to visualise profiling information
does not support reading GZip compressed profile files, whereas KCacheGrind and
PhpStorm do. If you are a QCacheGrind user, you should set
xdebug.use_compression to integer xdebug.var_display_max_children = 128 #Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace. To disable any limitation, use -1 as value. This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature. integer xdebug.var_display_max_data = 512 #Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace. To disable any limitation, use -1 as value. This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature. integer xdebug.var_display_max_depth = 3 #Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or when making a Function Trace. The maximum value you can select is 1023. You can also use -1 as value to select this maximum number. This setting does not have any influence on the number of children that is send to the client through the Step Debugging feature. Setting the value to a high number could potentially result in PHP using up all the available memory, so use with caution. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |