Xdebug prompts that the debugging client interface is connected to PHP running. This chapter explains how to set up PHP with xdebug, and recommends some clients.
Introduction
Xdebug's remote debugger allows you to inspect data structures, step through and debug your code interactively. The protocol is already open and is called DBGp. This protocol was implemented in xdebug2 and replaces an older GDB similar protocol that is no longer supported.
Client
Xdebug2 bundles a simple command line tool using the DBGp protocol. There are other clients that do a good job (free or commercial).
A simple command line tool for debugging is bundled in the debugclient
directory where xdebug is located.
Start debugger
To enable the xdebug debugger, you need to configure some settings in php.ini. Such settings include xdebug.remote_enable to enable the debugger, xdebug.remote_host and xdebug.remote_port to configure the IP address and port for the debugger to connect. There is also the xdebug.remote_connect_back setting for sharing the development server with multiple developers.
If you need the debugger to initiate a session when an error occurs (PHP error or exception), you also need to change the xdebug.remot_mode setting. Allowed values for this setting are "req" (default), which causes the heightener to initiate a session at the beginning of the script, or "jit", which causes the session value to be generated when an error occurs.
After setting all this up, xdebug still fails to automatically start a debugging session as soon as the script is run. You have three ways to activate the xdebug debugger:
1. When running the script in the command line, you need to set the environment variable:
export XDEBUG_CONFIG="idekey=session_name"
php myscript.php
You can also configure xdebug.remote_host, xdebug.remote_port, xdebug.remote_mode and xdebug.remote_handler as the same environment variables by isolating these values in a space:
export XDEBUG_CONFIG="idekey=session_name remote_host=localhost profiler_enable=1"
All settings you can set through XDEBUG_CONFIG in php.ini.
2. If you want to debug the script in the browser, just add XDEBUG_SESSION_START=session_name
参数
to the URL. To replace the GET parameter, you can also set XDEBUG_SESSTION_START as the POST parameter or the COOKIE parameter. Please refer to the next chapter for details.
3. To run PHP in the browser and activate the debugger, you need to install the following browser plug-in. Each plug-in lets you launch the debugger with the click of a button. When these plugins are activated, they will directly set the XDEBUG_SESSION cookie value instead of XDEBUG_SESSION_START.
The easiest Xdebug
The Firefox plug-in has an IDE interface for easier debugging. Plug-in address: https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/.
Xdebug Helper for Chrome
The Chrome plug-in helps you turn on or off debugging with just one click. Plug-in address: https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc.
Xdebug Toggler for Safari
The Safari plug-in can automatically enable Xdebug debugging. Github address: https://github.com/benmatselby/xdebug-toggler.
Xdebug launcher for Opera
The Opera plug-in allows you to open an xdebug debugging session.
Before you run the script, you want your client to be able to receive debug connections. Please refer to the article to specify how the client needs to be configured. To use the bundled simple client please refer to the Compilation and Installation chapter. You can use the branch "debug client".
When the debug client starts, it will display the following message and wait for the connection to be received by the debug server:
Xdebug Simple DBGp client (0.10.0)
Copyright 2002-2007 by Derick Rethans.
- libedit support: enabled
Waiting for debug server to connect.
When the connection is formed, the debug server will output the following information:
Connect
07ea142ddb434288baf1d3274187eee7
a0ac91dba639b9f18b388b013dd977af
30a6706cefdbe788e51b0304c4e53b96ea33106120d5fe79be4b228470e20dbb649ef0160e87b4fcf39b42d9b3808655
48fe722b397613e801e59f453d6c93309cdda9240b9fa678cc3dfff434392a5d069b8d673ec8f2ad312c1b3588acdb70
9bb6a7d109b3f2bf35f7e2e9bd87f98aeef2b59be4a93d7526f81ec5aefc50c3900f1908732f5dc023563361c92a4eee
0957585dd138d30c2391968169f40d39aa44b13fd2ef01269048c50cb9b1211498059fe0c8ea1ae7fb10b682743ca094
303f424bee22cca8251db2163a7ef073
(cmd)
Now you can use some command sets related to DBGp. When the script finishes running, the debugging server closes the connection with the client. The debug client resumes waiting for new connections.
Communication Settings
Static IP/single development
During remote debugging, xdebug built into PHP acts as the client, and the IDE acts as the server. The following animation shows the establishment of a communication channel:
Unknown IP/Multiple developers
If xdebug.remote_connect_back is used, the connection method is slightly different:
HTTP debugging session
Xdebug includes the function of using cookies to start a trace debugging session on the browser. The work is similar to the following steps:
Xdebug only allows an IP address specified during remote debugging to connect to xdebug.remote_host. It cannot connect back to the IP of the machine where the browser is running when the browser is running the test, unless you use xdebug.remote_connect_back.
If developers have various projects on the same (development) server, you can set each project through Apache's .htaccess function php_value xdebug.remote_host=10.0.0.5
and use the xdebug.remote_host setting.
There are two solutions here. First, you can use a DBGp proxy. As for how to use it, refer to the Debugging with multiple users chapter. You can download the agent software as part of the python remote debugging package at ActiveState's web site. More documentation is in the Komodo FAQ.
The second is to use the xdebug.remote_connect_back setting of xdebug 2.1.
xdebug.extended_info
Type: integer, default value: 1
Control whether xdebug forcibly turns on the "extended_info" mode of the PHP parser, which allows Xdebug to perform file/line number breakpoint debugging on remote debugging. When tracing or profiling scripts you usually want to turn this option off because the arrays produced by PHP will increase by a third in size and slow down your script. This setting can only be set in php.ini, not in ini_set().
xdebug.idekey
Type: string, Default value: *complex*
Controls which IDE index values can be passed by xdebug to the DBGp debug processor. The default is based on setting the environment. First the environment setting DBGP_IDEKEY is considered, then USER and finally USERNAME. The default value will be the first environment variable found. If it is indeed not found, the setting is the default "". If this value is set, it usually overrides the environment variable value.
xdebug.remote_autostart
Type: boolean, Default value: 0
Generally speaking, you need to use a specified HTTP GET/POST variable to start remote debugging (refer to Remote Debugging). When set to 1, Xdebug will attempt to start a remote debugging session and attempt to connect to a client, even if the GET/POST/COOKIE variable does not exist.
xdebug.remote_connect_back
Type: boolean, Default value: 0, since Xdebug > 2.1
If the setting is in effect, the xdebug.remote_host setting will be ignored and Xdebug will try to connect to the client making the HTTP request. It checks the $_SERVER['REMOTE_ADDR'] variable and finds out the IP address used. Keep in mind that there is no effective filtering, anyone can start a debug session and connect to the server, even if their address does not match xdebug.remote_host.
xdebug.remote_cookie_expire_time
Type: integer, Default value: 3600, since Xdebug > 2.1
Used to increase or decrease the cookie existence time of the remote debugging session.
xdebug.remote_enable
Type: boolean, Default value: 0
This switch controls Xdebug's attempt to communicate with the debugging client by setting the xdebug.remote_host and xdebug.remote_port listening server and port. When set to 0, the script is simply run but the connection cannot be established.
xdebug.remote_handler
Type: string, Default: dbgp
Can be changed to 'php3' to use the old PHP3 style debugger output, 'gdb' to enable GDB similar to the debugger interface, or 'dbgp' to use the debugger protocol. DBGp protocol is the only supported protocol.
Note: Version 2.1 or above only supports 'dbgp' as the protocol.
xdebug.remote_log
Type: string, Default value:
If set to a value, it is used as filename to a file to which all remote debugger communications are logged. The file is always opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available. The format of the file looks something like:
Log opened at 2007-05-27 14:28:15
-> 821f395ab97d640c582e626d3c58196b303f424bee22cca8251db2163a7ef073
a7c009fcbbb10abb7a3d97c19d957020 acf3621a137733e774e3512b98d069d35926afb69347ced47e61d1fa57648b84
xdebug.remote_mode
Type: string, Default value: req
Select the mode for debugging connection. There are two values:
req
When the debugging client starts the script and runs, Xdebug attempts to connect to the debugging client.
jit
Xdebug will only connect to the debug side when an error occurs.
xdebug.remote_port
Type: integer, default value: 9000
Xdebug attempts to connect to the port of the remote server. Port 9000 is the port associated with the default client and bound debugging client. Many clients use this port number, so it is recommended not to change it.
bool xdebug_break()
This function creates a debugging breakpoint at the specified line