XDEBUG from entry to mastery.

  php, test, xdebug



Xdebug is an extension of PHP to assist in debugging and development.

  • It contains a debugger for IDE
  • It upgraded PHP’svar_dump()Function
  • It adds stack traces for notifications, warnings, errors, and exceptions
  • It has the function of recording each function call and disk variable assignment
  • It contains an analyzer
  • It provides code coverage for use with PHPUnit.

An essential tool for apes.
However, xdebug is not recommended for production because it is too heavy.


PECL installation

pecl install xdebug

Source package installation

https://xdebug.org/download.phpFind the corresponding package

wget  xxx.gz
 make && make install

Docker installation

The following are some of the contents in php dockerfile.

RUN pecl install xdebug
 RUN echo 'zend_extension=xdebug.so' >> /usr/local/etc/php/conf.d/xdebug.ini

Working principle

IDE (such as PHPStorm) has integrated an XDebug plug-in that follows BGDP. When it is turned on, an XDebug debugging service will be opened locally to monitor the ports set in the debugger. The default is 9000, and this service will monitor all links to 9000 ports.


When the browser sends a request with the parameter XDEBUG_SESSION_START to the server, the server accepts it and transfers it to the back-end php for processing. if php opens the XDebug module, the debug information will be forwarded to the debug port of the IDE of the client IP.


When there is no XDEBUG_SESSION_START in the parameter or cookie information, debugging will not be started. This makes it possible to add switches to the browser later.

Basic configuration

Under normal circumstances, you only need to understand and do not need to modify.

Name Type Default value annotation
xdebug.default_enable boolean 1 Stack trace, which is turned on by default, is one of the basic functions of xdebug.
xdebug.force_display_errors integer 0 The default is off. If this setting is set to 1, then errors will always be displayed regardless of PHP’s display_errors setting.
xdebug.force_error_reporting integer 0 The default is off, allowing some errors to be forced to appear.
xdebug.halt_level integer 0 It is turned off by default and set to receive some specified errors.
xdebug.max_nesting_level integer 256 The default protection mechanism for controlling infinite recursion (dead loop) is 256
xdebug.max_stack_frames integer -1 Controls how many stack frames are displayed in the stack trace, in the command line of PHP error stack trace, and in the browser HTML trace.
xdebug.scream boolean 0 The default is off. If this setting is 1, Xdebug will disable the @ (off) operator so that notifications, warnings, and errors are no longer hidden.

Please move to the official website for detailshttps://xdebug.org/docs/basic

Print configuration

Xdebug will replace PHP’s var_dump () function to display variables. The Xdebug version contains different types of colors and limits the number, maximum depth and string length of array elements/object attributes. There are other functions that also handle variable display.

Name Type Default value annotation
xdebug.cli_color integer 0 Does the input result set color in cli mode
xdebug.overload_var_dump boolean 2 Allow xdebug to overload var_dump function
xdebug.var_display_max_children integer 128 Var_dump limits the number of display layers for the children of array objects
xdebug.var_display_max_data integer 512 Var_dump limit on result length
xdebug.var_display_max_depth integer 3 Var_dump Limit on the Number of Nested Layers to Display by Default

Please move to the official website for detailshttps://xdebug.org/docs/display

Stack trace configuration

When Xdebug is activated, PHP will display a stack trace when it decides to display a notification, warning, error, etc. The information displayed by the stack trace and how they are displayed can be configured to suit your needs.

Name Type Default value annotation
xdebug.cli_color integer 0 Does the input result set color in cli mode
xdebug.collect_includes boolean 1 Controls whether Xdebug should write the file name in include (), include_once (), require (), or require_once () to the trace file
xdebug.collect_params integer 0 This setting defaults to 0 and controls whether Xdebug should collect the parameters passed to the function when the function trace or stack trace records the function call.
xdebug.collect_vars boolean 0 This setting tells Xdebug which variables to use within a specific range. Since Xdebug must reverse engineer PHP’s opcode array, this analysis can be quite slow. For using xdebug.collect_params, this setting does not record the values of different variables. This setting needs to be enabled only if you want to use xdebug_get_declared_vars ().
xdebug.dump.* string empty * can be any COOKIE, file, GET, POST, REQUEST, SERVER, SESSION. These seven settings control which data from super-global variables are displayed when an error occurs.
xdebug.dump_globals boolean 1 When this setting is set to true, Xdebug will add the value * of the super global variable configured through Xdebug.dump to the stack trace and error log on the screen.
xdebug.dump_once boolean 1 Controls whether the value of the superglobal variable should be transferred in all error cases (set to 0), or only in the first error case (set to 1)
xdebug.dump_undefined boolean 0 If you want to dump undefined values from super-global variables, you should set this setting to 1, otherwise set it to 0.
xdebug.file_link_format string File link format

Please move to the official website for detailshttps://xdebug.org/docs/stack …

Function debug configuration

Xdebug allows recording of all function calls, including parameters and values returned in different formats.

Name Type Default value annotation
xdebug.auto_trace boolean 0 When this setting is set to ture, tracing of function calls will be enabled before the script runs.
xdebug.collect_assignments boolean 0 This setting defaults to 0 and controls whether Xdebug should add variable assignments to function traces.
xdebug.collect_includes boolean 1 This setting defaults to 1 and controls whether Xdebug should write the file names in include (), include_once (), require (), or require_once () to the trace file.
xdebug.collect_params integer 0 This setting defaults to 0 and controls whether Xdebug should collect the parameters passed to the function when the function trace or stack trace records the function call.
xdebug.collect_return boolean 0 This setting defaults to 0 and controls whether Xdebug should write the return value of the function call to the trace file.
xdebug.show_mem_delta integer 0 The trace file generated by Xdebug will show the difference in memory usage between function calls
xdebug.trace_format integer 0 Format of trace file
xdebug.trace_options integer 0 When set to “1”, the trace file will be appended to subsequent requests instead of being overwritten.
xdebug.trace_output_dir string /tmp Write to the directory of the trace file to ensure that the user running PHP has write permission to the directory.

Please move to the official website for detailshttps://xdebug.org/docs/execu …

Garbage collection statistics

Xdebug’s built-in garbage collection statistics analyzer allows you to find out when the PHP internal garbage collector triggered, how many variables it was able to clean, how long it took, and how much memory it actually freed.

Name Type Default value annotation
xdebug.gc_stats_enable bool false If you enable this setting, statistics for garbage collection runs will be automatically collected into the given directory set using xdebug.gc_stats_output_dir and will use the automatically generated name configured by xdebug.gc_stats_output_name.
xdebug.gc_stats_output_dir string /tmp The directory where garbage collection statistics are output will be written to ensure that the user who will run PHP has write permissions to the directory. You cannot use ini_set () to set this setting in the script.
xdebug.gc_stats_output_name string gcstats.%p This setting determines the name of the file used to dump garbage collection statistics. This setting uses the format specifier to specify the format, much like sprintf () and strftime (). There are several format specifiers that can be used to format file names.

Please move to the official website for detailshttps://xdebug.org/docs/garba …

Remote debugging configuration

Xdebug provides an interface for debugger clients that interact with PHP scripts.

Name Type Default value annotation
xdebug.extended_info integer 1 Controls whether Xdebug should enforce’ extended_info’ mode for PHP parsers; This allows Xdebug to use a remote debugger to execute file/line breakpoints. When tracing or analyzing scripts, you usually want to turn off this option, because the oparray generated by PHP will increase by about one third, thus slowing down the script speed. This setting cannot be set in scripts using ini_set (), but can only be set in php.ini.
xdebug.idekey string complex Controls which IDE Key Xdebug should be passed to DBGp debugger handlers. The key that communicates with the client
xdebug.remote_addr_header string “” This value will be used as a key in the $SERVER super global array to determine the header used to find the IP address or hostname used for “connect back.”
xdebug.remote_autostart boolean 0 You need to use a specific HTTP GET/POST variable to start remote debugging
xdebug.remote_connect_back boolean 0 If you do not set the ip address, you can only rely on Xdebug to find it. xdebug will try to connect to the client that makes the HTTP request. It checks $ _ server [‘http _ x _ forwarded _ for’] and $_SERVER[‘REMOTE_ADDR’] variables to find the IP address to use
xdebug.remote_cookie_expire_time integer 3600 Set cookie life cycle
xdebug.remote_enable boolean 0 Do you want to turn on remote debugging?
xdebug.remote_handler string dbgp Debugged communication protocol
xdebug.remote_host string localhost The debug network address, after opening the remote_connect_back, the current configuration is invalid
xdebug.remote_log string Debugging log
xdebug.remote_port integer 9000 Debugged port
xdebug.remote_timeout integer 200 Waiting Time for Debugged Communication Links

Please move to the official website for detailshttps://xdebug.org/docs/remote

Official link

Please move to the official website for all configurations.https://xdebug.org/docs/all_s …
Please move to the official website for all functionshttps://xdebug.org/docs/all_f …


The configuration DEBUG articles on the network are too miscellaneous and confusing. It is really disturbing to jump around in PHPSTROM. This chapter rearranges the description.


In fact, there are already very detailed tutorials in PHPSTROM, right? However, most people will directly use Baidu /Google. It is a good habit to inquire, but it depends on the situation.

Languages & Frameworks > PHP > Debug


First step

Download the XDEBUG extension, which has already been mentioned at the beginning of this chapter and will not be described here.
After the installation is complete, PHPSTROM provides a validation script. The script address ishttps://gist.github.com/litzi …
Under normal circumstances, the appearance of successful detection is


Seeing this, you can go to debug with confidence.

Second step

Install a browser plug-in and the user requests to listen. The only function of this thing is to facilitate debug. normally, if you don’t install it, you need to pass parameters through GET.XDEBUG_SESSION_START=ID_KEYOnly then, after installing the plug-in, it is unnecessary.


You can choose whether to open debug. The following is a list of browser plug-ins

Browser download
Chrome Xdebug Helper
Firefox The easiest XdebugorXdebug Helper
Safari Xdebug Toggler
Opera Xdebug launcher
Internet Explorer PhpStorm bookmarklets generator

Third step

Just turn on the monitor.


You can directly click the monitor button on the picture.

So far, the IDE has been configured.

Fourth step

Create a DEBUG configuration file that is configured for each project. You can’t run this step.


As you can see, PHPSTORM is very humane and will give you a simple tutorial at every step to describe how to configure DEBUG.

Add a Server and idkey to debug.


Summarize the following IDE steps for configuring DEBUG, which is actually very simple.

  1. Download and install debug
  2. Verify proper communication
  3. Add browser plug-in (optional)
  4. Configure the run file
  5. Happy debug

Also note here that if you don’t need to access the machine to debug some classes or code blocks, you only need to install XDEBUG on the machine, all the above configurations are omitted, and you can debug by clicking the bug icon directly. The DEBUG port defaults to 9000. If it is modified in the configuration file, of course it needs to be modified in the IDE.


Introduce what the buttons of PHPSTORM panel are used for in the actual DEBUG process. When you start monitoring, you will see the following figure


According to the icon position in the above figure, describe the function of each icon in x and y coordinates.

Icon Location (x,y) Function
clipboard.png 0,0 Rerun Debug (Rerun test.php)
clipboard.png 0,1 Jump to the original debug file (Show execution point)
clipboard.png 0,2 Skip to the next line
clipboard.png 0,3 Perform the next Step info
clipboard.png 0,4 Jump into a warehouse, constructor, or other method or class (Force Step Info)
clipboard.png 0,5 Executes the function body or class method, and ends this Step out if it is at the outermost layer.
clipboard.png 0,6 Jump to the current node’s next breakpoint (Run to Cursor)
clipboard.png 0,7 The modified variable is executed or the returned result is used for secondary debugging (Evaluate arbitrary expression)
clipboard.png 0,8 Show Values Addresses
clipboard.png 0,9 Whether to display empty values is not displayed by default
clipboard.png 0,10 Jump to next breakpoint (Add method to skip list)
clipboard.png 1,0 Re-execute DEBUG (Resume Program.
clipboard.png 2,0 Stop DEBUG(Step process)
clipboard.png 3,0 View and manage all breakpoints
clipboard.png 4,0 Ignore all breakpoints



Some people have installed Docker on this machine and run this PHP in the container. How to DEBUG at this time? If you read this article carefully, you will find it very simple. XDEBUG itself is remote debugging. First of all, you have to promise

  • The container is port mapped to the native 80
  • The project directory in the container is mounted on disk.

In the container PHP XDEBUG


You can, and you don’t have to worry about the hosts file.

Local IP = = localhost

After this configuration is completed, the container can be used when it does not exist, just like the debugging of this machine.

Thank you

Thank you for seeing here. I hope this chapter can help you. Thank you.