Installation
This section describes on how to install Xdebug.
Precompiled Windows Modules
There are a few precompiled modules for Windows, they are all for the non-debug version of PHP. You can get those at the download page. Follow these instructions to get Xdebug installed.
PECL Installation
As of Xdebug 0.9.0 you can install Xdebug through PEAR/PECL. This only works with with PEAR version 0.9.1-dev or higher and some UNIX.
Installing with PEAR/PECL is as easy as:
# pecl install xdebug
but you still need to add the correct line to your php.ini: (don't forget to change the path and filename to the correct one — but make sure you use the full path)
zend_extension="/usr/local/php/modules/xdebug.so"
Note: You should ignore any prompts to add "extension=xdebug.so" to php.ini — this will cause problems.
Installation on Mac OS X via Homebrew
PHP and Xdebug are available from the unofficial Mac OS X package manager Homebrew. If you use PHP installed via Homebrew (see this installation guide for details on how to do that) Xdebug can be installed via brew install:
# brew install <php-version>-xdebug
eg.
# brew install php56-xdebug
You can also use brew search to locate the specific package you need:
# brew search xdebug
The Xdebug extension will be enabled per default after the installation, additional configuration of the extension should be done by adding a custom ini-file to /usr/local/etc/php/<php-version>/conf.d/ . See the Caveats output at the end of the installation for more details.
Installation From Source
You can download the source of the latest stable release 2.2.5. Alternatively you can obtain Xdebug from GIT:
git clone git://github.com/xdebug/xdebug.git
This will checkout the latest development version which is currently 2.2.5. You can also browse the source at https://github.com/derickr/xdebug.
Compiling
There is a wizard available that provides you with the correct file to download, and which paths to use.
You compile Xdebug separately from the rest of PHP. Note, however,
that you need access to the scripts 'phpize' and 'php-config'. If
your system does not have 'phpize' and 'php-config', you will need to
compile and install PHP from a source tarball first, as these script
are by-products of the PHP compilation and installation processes. (Debian users
can install the required tools with
apt-get install php5-dev). It is important that the source version
matches the installed version as there are slight, but important, differences
between PHP versions. Once you have access to 'phpize' and
'php-config', do the following:
- Unpack the tarball: tar -xzf xdebug-2.2.5.tgz. Note that you do not need to unpack the tarball inside the PHP source code tree. Xdebug is compiled separately, all by itself, as stated above.
- cd xdebug-2.2.5
- Run phpize: phpize (or /path/to/phpize if phpize is not in your path). Make sure you use the phpize that belongs to the PHP version that you want to use Xdebug with. See this FAQ entry if you're having some issues with finding which phpize to use.
- ./configure --enable-xdebug
- make
- make install
Configure PHP to Use Xdebug
- add the following line to php.ini: zend_extension="/wherever/you/put/it/xdebug.so". For PHP versions earlier than 5.3 and threaded usage of PHP (Apache 2 worker MPM or the ISAPI module), add: zend_extension_ts="/wherever/you/put/it/xdebug.so" instead. Note: In case you compiled PHP yourself and used --enable-debug you would have to use zend_extension_debug=. Note: If you want to use Xdebug and OPCache together, you must load Xdebug after OPCache. Otherwise, they won't work properly. From PHP 5.3 onwards, you always need to use the zend_extension PHP.ini setting name, and not zend_extension_ts, nor zend_extension_debug. However, your compile options (ZTS/normal build; debug/non-debug) still need to match with what PHP is using.
- Restart your webserver.
- Write a PHP page that calls 'phpinfo()' Load it in a browser and look for the info on the Xdebug module. If you see it next to the Zend logo, you have been successful! You can also use 'php -m' if you have a command line version of PHP, it lists all loaded modules. Xdebug should appear twice there (once under 'PHP Modules' and once under 'Zend Modules').
Compatibility
Xdebug does not work together with the Zend Optimizer or any other extension that deals with PHP's internals (DBG, APD, ioncube etc). This is due to compatibility problems with those modules.
Debugclient Installation
Unpack the Xdebug source tarball and issue the following commands:
$ cd debugclient $ ./configure --with-libedit $ make # make install
This will install the debugclient binary in /usr/local/bin unless you don't
have libedit installed on your system. You can either install it, or leave
out the '--with-libedit' option to configure. Debian 'unstable' users can
install the library with apt-get install libedit-dev libedit2.
If the configure script can not find libedit and you are sure you have (and it's headers) installed correctly and you get link errors like the following in your configure.log:
/usr/lib64/libedit.so: undefined reference to `tgetnum' /usr/lib64/libedit.so: undefined reference to `tgoto' /usr/lib64/libedit.so: undefined reference to `tgetflag' /usr/lib64/libedit.so: undefined reference to `tputs' /usr/lib64/libedit.so: undefined reference to `tgetent' /usr/lib64/libedit.so: undefined reference to `tgetstr' collect2: ld returned 1 exit status
you need to change your configure command to:
$ LDFLAGS=-lncurses ./configure --with-libedit
Variable Display Features
Xdebug replaces PHP's var_dump() function for displaying variables. Xdebug's version includes different colors for different types and places limits on the amount of array elements/object properties, maximum depth and string lengths. There are a few other functions dealing with variable display as well.
Effect of settings on var_dump()
There is a number of settings that control the output of Xdebug's modified var_dump() function: xdebug.var_display_max_children, xdebug.var_display_max_data and xdebug.var_display_max_depth. The effect of these three settings is best shown with an example. The script below is run four time, each time with different settings. You can use the tabs to see the difference.
The script
<?php
class test {
public $pub = false;
private $priv = true;
protected $prot = 42;
}
$t = new test;
$t->pub = $t;
$data = array(
'one' => 'a somewhat long string!',
'two' => array(
'two.one' => array(
'two.one.zero' => 210,
'two.one.one' => array(
'two.one.one.zero' => 3.141592564,
'two.one.one.one' => 2.7,
),
),
),
'three' => $t,
'four' => range(0, 5),
);
var_dump( $data );
?>
The results
array
'one' => string 'a somewhat long string!' (length=23)
'two' =>
array
'two.one' =>
array
'two.one.zero' => int 210
'two.one.one' =>
array
...
'three' =>
object(test)[1]
public 'pub' =>
&object(test)[1]
private 'priv' => boolean true
protected 'prot' => int 42
'four' =>
array
0 => int 0
1 => int 1
2 => int 2
3 => int 3
4 => int 4
5 => int 5
array
'one' => string 'a somewhat long string!' (length=23)
'two' =>
array
'two.one' =>
array
'two.one.zero' => int 210
'two.one.one' =>
array
...
more elements...
array
'one' => string 'a somewhat long '... (length=23)
'two' =>
array
'two.one' =>
array
'two.one.zero' => int 210
'two.one.one' =>
array
...
'three' =>
object(test)[1]
public 'pub' =>
&object(test)[1]
private 'priv' => boolean true
protected 'prot' => int 42
'four' =>
array
0 => int 0
1 => int 1
2 => int 2
3 => int 3
4 => int 4
5 => int 5
array
'one' => string 'a somewhat long string!' (length=23)
'two' =>
array
'two.one' =>
array
...
'three' =>
object(test)[1]
public 'pub' =>
&object(test)[1]
private 'priv' => boolean true
protected 'prot' => int 42
'four' =>
array
0 => int 0
1 => int 1
2 => int 2
3 => int 3
4 => int 4
5 => int 5
array
'one' => string 'a somewh'... (length=23)
'two' =>
array
...
'three' =>
object(test)[1]
...
more elements...
Related Settings
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.
By default Xdebug overloads var_dump() with its own improved version
for displaying variables when the html_errors php.ini setting is set to
1 or 2. In case you do not want that, you can
set this setting to 0, but check first if it's not smarter
to turn off html_errors.
You can also use 2 as value for this setting. Besides
formatting the var_dump() output nicely, it will also add filename and
line number to the output. The xdebug.file_link_format setting is also
respected. (New in Xdebug 2.3)
Before Xdebug 2.4, the default value of this setting was
1.
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 through Function Traces.
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 Remote Debugging feature.
Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or through Function Traces.
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 Remote Debugging feature.
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 through Function Traces.
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 Remote Debugging feature.
Related Functions
This function is overloaded by Xdebug, see the description for xdebug_var_dump().
This function displays structured information about one or more variables that includes its type, value and refcount information. Arrays are explored recursively with values. This function is implemented differently from PHP's debug_zval_dump() function in order to work around the problems that that function has because the variable itself is actually passed to the function. Xdebug's version is better as it uses the variable name to lookup the variable in the internal symbol table and accesses all the properties directly without having to deal with actually passing a variable to a function. The result is that the information that this function returns is much more accurate than PHP's own function for showing zval information.
Support for anything but simple variable names (such as "a[2]" below) is supported since Xdebug 2.3.
<?php
$a = array(1, 2, 3);
$b =& $a;
$c =& $a[2];
xdebug_debug_zval('a');
xdebug_debug_zval("a[2]");
?>
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)=1, 1 => (refcount=1, is_ref=0)=2, 2 => (refcount=2, is_ref=1)=3) a[2]: (refcount=2, is_ref=1)=3
This function displays structured information about one or more variables that includes its type, value and refcount information. Arrays are explored recursively with values. The difference with xdebug_debug_zval() is that the information is not displayed through a web server API layer, but directly shown on stdout (so that when you run it with Apache in single process mode it ends up on the console).
<?php
$a = array(1, 2, 3);
$b =& $a;
$c =& $a[2];
xdebug_debug_zval_stdout('a');
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)=1, 1 => (refcount=1, is_ref=0)=2, 2 => (refcount=2, is_ref=1)=3)
This function dumps the values of the elements of the super globals as specified with the xdebug.dump.* php.ini settings. For the example below the settings in php.ini are:
xdebug.dump.GET=*
xdebug.dump.SERVER=REMOTE_ADDR
Query string:
?var=fourty%20two&array[a]=a&array[9]=b
| Dump $_SERVER | ||||
|---|---|---|---|---|
$_SERVER['REMOTE_ADDR'] = | string '127.0.0.1' (length=9) | |||
| Dump $_GET | ||||
$_GET['var'] = | string 'fourty two' (length=10) | |||
$_GET['array'] = | array 'a' => string 'a' (length=1) 9 => string 'b' (length=1) | |||
This function displays structured information about one or more expressions that includes its type and value. Arrays are explored recursively with values. See the introduction of Variable Display Features on which php.ini settings affect this function.
<?php
ini_set('xdebug.var_display_max_children', 3 );
$c = new stdClass;
$c->foo = 'bar';
$c->file = fopen( '/etc/passwd', 'r' );
var_dump(
array(
array(TRUE, 2, 3.14, 'foo'),
'object' => $c
)
);
?>
array
0 =>
array
0 => boolean true
1 => int 2
2 => float 3.14
more elements...
'object' =>
object(stdClass)[1]
public 'foo' => string 'bar' (length=3)
public 'file' => resource(3, stream)
Stack Traces
When Xdebug is activated it will show a stack trace whenever PHP decides to show a notice, warning, error etc. The information that stack traces display, and the way how they are presented, can be configured to suit your needs.
The stack traces that Xdebug shows on error situations (if display_errors is set to On in php.ini) are quite conservative in the amount of information that they show. This is because large amounts of information can slow down both the execution of the scripts and the rendering of the stack traces themselves in the browser. However, it is possible to make the stack traces show more detailed information with different settings.
Variables in Stack Traces
By default Xdebug will now show variable information in the stack traces that it produces. Variable information can take quite a bit of resources, both while collecting or displaying. However, in many cases it is useful that variable information is displayed, and that is why Xdebug has the setting xdebug.collect_params. The script below, in combination with what the output will look like with different values of this setting is shown in the example below.
The script
<?php
function foo( $a ) {
for ($i = 1; $i < $a['foo']; $i++) {
if ($i == 500000) xdebug_break();
}
}
set_time_limit(1);
$c = new stdClass;
$c->bar = 100;
$a = array(
42 => false, 'foo' => 912124,
$c, new stdClass, fopen( '/etc/passwd', 'r' )
);
foo( $a );
?>
The results
Different values for the xdebug.collect_params setting give different output, which you can see below:
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 34 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58564 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62764 | foo( ) | ../stack.php:47 |
ini_set('xdebug.collect_params', '1');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 31 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58132 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62380 | foo( array(5) ) | ../stack.php:47 |
ini_set('xdebug.collect_params', '2');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 31 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58564 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62812 | foo( array(5) ) | ../stack.php:47 |
ini_set('xdebug.collect_params', '3');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 31 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58564 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62812 | foo( array (42 => FALSE, 'foo' => 912124, 43 => class stdClass { public $bar = 100 }, 44 => class stdClass { }, 45 => resource(2) of type (stream)) ) | ../stack.php:47 |
ini_set('xdebug.collect_params', '4');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 31 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58132 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62380 | foo( $a = array (42 => FALSE, 'foo' => 912124, 43 => class stdClass { public $bar = 100 }, 44 => class stdClass { }, 45 => resource(2) of type (stream)) ) | ../stack.php:47 |
Additional Information
On top of showing the values of variables that were passed to each function Xdebug can also optionally show information about selected superglobals by using the xdebug.dump_globals and xdebug.dump.* settings. The settings xdebug.dump_once and xdebug.dump_undefined slightly modify when and which information is shown from the available superglobals. With the xdebug.show_local_vars setting you can instruct Xdebug to show all variables available in the top-most stack level for a user defined function as well. The examples below show this (the script is used from the example above).
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 34 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58564 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62764 | foo( ) | ../stack.php:47 |
ini_set('xdebug.collect_vars', 'on');
ini_set('xdebug.collect_params', '4');
ini_set('xdebug.dump_globals', 'on');
ini_set('xdebug.dump.SERVER', 'REQUEST_URI');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 33 | ||||
|---|---|---|---|---|
| Call Stack | ||||
| # | Time | Memory | Function | Location |
| 1 | 0.0001 | 58132 | {main}( ) | ../stack.php:0 |
| 2 | 0.0004 | 62436 | foo( ) | ../stack.php:47 |
| Dump $_SERVER | ||||
$_SERVER['REQUEST_URI'] = | string '/test/xdebug/docs/stack.php?level=5' (length=35) | |||
ini_set('xdebug.collect_vars', 'on');
ini_set('xdebug.collect_params', '4');
ini_set('xdebug.dump_globals', 'on');
ini_set('xdebug.dump.SERVER', 'REQUEST_URI');
ini_set('xdebug.show_local_vars', 'on');
| ( ! ) Fatal error: Maximum execution time of 1 second exceeded in /home/httpd/html/test/xdebug/docs/stack.php on line 31 | |||||
|---|---|---|---|---|---|
| Call Stack | |||||
| # | Time | Memory | Function | Location | |
| 1 | 0.0001 | 58132 | {main}( ) | ../stack.php:0 | |
| 2 | 0.0005 | 62588 | foo( ) | ../stack.php:47 | |
| Dump $_SERVER | |||||
$_SERVER['REQUEST_URI'] = | string '/test/xdebug/docs/stack.php?level=6' (length=35) | ||||
| Variables in local scope (#2) | |||||
$a = | array
42 => boolean false
'foo' => int 912124
43 =>
object(stdClass)[1]
public 'bar' => int 100
44 =>
object(stdClass)[2]
45 => resource(2, stream)
| ||||
$i = | int 275447 | ||||
Related Settings
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, defaulting to 0, controls whether Xdebug should collect the parameters passed to functions when a function call is recorded in either the function trace or the stack trace.
The setting defaults to 0 because for very large scripts it may use huge amounts of memory and therefore make it impossible for the huge script to run. You can most safely turn this setting on, but you can expect some problems in scripts with a lot of function calls and/or huge data structures as parameters. Xdebug 2 will not have this problem with increased memory usage, as it will never store this information in memory. Instead it will only be written to disk. This means that you need to have a look at the disk usage though.
This setting can have four different values. For each of the values a different amount of information is shown. Below you will see what information each of the values provides. See also the introduction of the feature Stack Traces for a few screenshots.
| Value | Argument Information Shown |
|---|---|
| 0 | None. |
| 1 | Type and number of elements (f.e. string(6), array(8)). |
| 2 | Type and number of elements, with a tool tip for the full information 1. |
| 3 | Full variable contents (with the limits respected as set by xdebug.var_display_max_children, xdebug.var_display_max_data and xdebug.var_display_max_depth. |
| 4 | Full variable contents and variable name. |
| 5 | PHP serialized variable contents, without the name. (New in Xdebug 2.3) |
1 in the CLI version of PHP it will not have the tool tip, nor in output files.
* 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 seperated list of
variables from this superglobal to dump, or * for all of them.
Make sure you do not add spaces in this setting.
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 = *
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:
| Specifier | Meaning |
|---|---|
| %f | the filename |
| %l | the line number |
For various IDEs/OSses there are some instructions listed on how to make this work:
Firefox on Linux
- Open about:config
- Add a new boolean setting "network.protocol-handler.expose.xdebug" and set it to "false"
- Add the following into a shell script
~/bin/ff-xdebug.sh:#! /bin/sh f=`echo $1 | cut -d @ -f 1 | sed 's/xdebug:\/\///'` l=`echo $1 | cut -d @ -f 2`
Add to that one of (depending whether you have komodo, gvim or netbeans):komodo $f -l $lgvim --remote-tab +$l $fnetbeans "$f:$l"
- Make the script executable with
chmod +x ~/bin/ff-xdebug.sh - Set the xdebug.file_link_format setting to
xdebug://%f@%l
Windows and netbeans
- Create the file
netbeans.batand save it in your path (C:\Windowswill work):@echo off setlocal enableextensions enabledelayedexpansion set NETBEANS=%1 set FILE=%~2 %NETBEANS% --nosplash --console suppress --open "%FILE:~19%" nircmd win activate process netbeans.exe
Note: Remove the last line if you don't have
nircmd. - Save the following code as
netbeans_protocol.reg:Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\netbeans] "URL Protocol"="" @="URL:Netbeans Protocol" [HKEY_CLASSES_ROOT\netbeans\DefaultIcon] @="\"C:\\Program Files\\NetBeans 7.1.1\\bin\\netbeans.exe,1\"" [HKEY_CLASSES_ROOT\netbeans\shell] [HKEY_CLASSES_ROOT\netbeans\shell\open] [HKEY_CLASSES_ROOT\netbeans\shell\open\command] @="\"C:\\Windows\\netbeans.bat\" \"C:\\Program Files\\NetBeans 7.1.1\\bin\\netbeans.exe\" \"%1\""
Note: Make sure to change the path to Netbeans (twice), as well as the
netbeans.batbatch file if you saved it somewhere else thanC:\Windows\. - Double click on the
netbeans_protocol.regfile to import it into the registry. - Set the xdebug.file_link_format setting to
xdebug.file_link_format = "netbeans://open/?f=%f:%l"
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.
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 through Function Traces.
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 Remote Debugging feature.
Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or through Function Traces.
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 Remote Debugging feature.
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 through Function Traces.
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 Remote Debugging feature.
Related Functions
Returns an array where each element is a variable name which is defined in the current scope. The setting xdebug.collect_vars needs to be enabled.
<?php
class strings {
static function fix_strings($a, $b) {
foreach ($b as $item) {
}
var_dump(xdebug_get_declared_vars());
}
}
strings::fix_strings(array(1,2,3), array(4,5,6));
?>
array 0 => string 'a' (length=1) 1 => string 'b' (length=1) 2 => string 'item' (length=4)
In PHP versions before 5.1, the variable name "a" is not in the returned array, as it is not used in the scope where the function xdebug_get_declared_vars() is called in.
Returns an array which resembles the stack trace up to this point. The example script:
<?php
class strings {
function fix_string($a)
{
var_dump(xdebug_get_function_stack());
}
function fix_strings($b) {
foreach ($b as $item) {
$this->fix_string($item);
}
}
}
$s = new strings();
$ret = $s->fix_strings(array('Derick'));
?>
array
0 =>
array
'function' => string '{main}' (length=6)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 0
'params' =>
array
empty
1 =>
array
'function' => string 'fix_strings' (length=11)
'class' => string 'strings' (length=7)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 18
'params' =>
array
'b' => string 'array (0 => 'Derick')' (length=21)
2 =>
array
'function' => string 'fix_string' (length=10)
'class' => string 'strings' (length=7)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 12
'params' =>
array
'a' => string ''Derick'' (length=8)
Returns a structure which contains information about where the monitored functions were executed in your script. The following example shows how to use this, and the returned information:
<?php
/* Start the function monitor for strrev and array_push: */
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );
/* Run some code: */
echo strrev("yes!"), "\n";
echo strrev("yes!"), "\n";
var_dump(xdebug_get_monitored_functions());
xdebug_stop_function_monitor();
?>
/tmp/monitor-example.php:10:
array(2) {
[0] =>
array(3) {
'function' =>
string(6) "strrev"
'filename' =>
string(24) "/tmp/monitor-example.php"
'lineno' =>
int(6)
}
[1] =>
array(3) {
'function' =>
string(6) "strrev"
'filename' =>
string(24) "/tmp/monitor-example.php"
'lineno' =>
int(8)
}
}
Returns the stack depth level. The main body of a script is level 0 and each include and/or function call adds one to the stack depth level.
Displays the current function stack, in a similar way as what Xdebug would display in an error situation.
The "message" argument allows you to replace the message in the header with your own. (Introduced in Xdebug 2.1).
<?php
function foo( $far, $out )
{
xdebug_print_function_stack( 'Your own message' );
}
foo( 42, 3141592654 );
?>
( ! ) Xdebug: Your own message in /home/httpd/html/test/xdebug/print_function_stack.php on line 5 Call Stack # Time Memory Function Location 1 0.0006 653896 {main}( ) ../print_function_stack.php:0 2 0.0007 654616 foo( 42, 3141592654 ) ../print_function_stack.php:7 3 0.0007 654736 xdebug_print_function_stack ( 'Your own message' ) ../print_function_stack.php:5
The bitmask "options" allows you to configure a few extra options. The following options are currently supported:
XDEBUG_STACK_NO_DESC- If this option is set, then the printed stack trace will not have a
header. This is useful if you want to print a stack trace from your own error
handler, as otherwise the printed location is where
xdebug_print_function_stack()was called from. (Introduced in Xdebug 2.3).
This function starts the monitoring of functions that were given in a list as argument to this function. Function monitoring allows you to find out where in your code the functions that you provided as argument are called from. This can be used to track where old, or, discouraged functions are used.
<?php
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );
?>
You can also add class methods and static methods to the array that defines which functions to monitor. For example, to catch static calls to DramModel::canSee and dynamic calls to Whisky->drink, you would start the monitor with:
<?php
xdebug_start_function_monitor( [ 'DramModel::canSee', 'Whisky->drink'] );
?>
The defined functions are case sensitive, and a dynamic call to a static method will not be caught.
This function stops the function monitor. In order to get the list of monitored functions, you need to use the xdebug_get_monitored_functions() function.
Function Traces
Xdebug allows you to log all function calls, including parameters and return values to a file in different formats.
Those so-called "function traces" can be a help for when you are new to an application or when you are trying to figure out what exactly is going on when your application is running. The function traces can optionally also show the values of variables passed to the functions and methods, and also return values. In the default traces those two elements are not available.
Output Formats
There are three output formats. One is meant as a human readable trace, another one is more suited for computer programs as it is easier to parse, and the last one uses HTML for formatting the trace. You can switch between the two different formats with the xdebug.trace_format setting. There are a few settings that control which information is written to the trace files. There are settings for including variables (xdebug.collect_params) and for including return values (xdebug.collect_return) for example. The example below shows what effect the different settings have for the human readable function traces.
The Script
<?php
$str = "Xdebug";
function ret_ord( $c )
{
return ord( $c );
}
foreach ( str_split( $str ) as $char )
{
echo $char, ": ", ret_ord( $char ), "\n";
}
?>
The Results
Below are the results with different settings of the xdebug.collect_params setting. As this is not a web environment the value of 2 does not have any meaning as tool tips don't work in text files.
TRACE START [2007-05-06 14:37:06]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split() ../trace.php:8
0.0153 117424 -> ret_ord() ../trace.php:10
0.0165 117584 -> ord() ../trace.php:5
0.0166 117584 -> ret_ord() ../trace.php:10
0.0167 117584 -> ord() ../trace.php:5
0.0168 117584 -> ret_ord() ../trace.php:10
0.0168 117584 -> ord() ../trace.php:5
0.0170 117584 -> ret_ord() ../trace.php:10
0.0170 117584 -> ord() ../trace.php:5
0.0172 117584 -> ret_ord() ../trace.php:10
0.0172 117584 -> ord() ../trace.php:5
0.0173 117584 -> ret_ord() ../trace.php:10
0.0174 117584 -> ord() ../trace.php:5
0.0177 41152
TRACE END [2007-05-06 14:37:07]
TRACE START [2007-05-06 14:37:11]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split(string(6)) ../trace.php:8
0.0007 117424 -> ret_ord(string(1)) ../trace.php:10
0.0007 117584 -> ord(string(1)) ../trace.php:5
0.0009 117584 -> ret_ord(string(1)) ../trace.php:10
0.0009 117584 -> ord(string(1)) ../trace.php:5
0.0010 117584 -> ret_ord(string(1)) ../trace.php:10
0.0011 117584 -> ord(string(1)) ../trace.php:5
0.0012 117584 -> ret_ord(string(1)) ../trace.php:10
0.0013 117584 -> ord(string(1)) ../trace.php:5
0.0014 117584 -> ret_ord(string(1)) ../trace.php:10
0.0014 117584 -> ord(string(1)) ../trace.php:5
0.0016 117584 -> ret_ord(string(1)) ../trace.php:10
0.0016 117584 -> ord(string(1)) ../trace.php:5
0.0019 41152
TRACE END [2007-05-06 14:37:11]
TRACE START [2007-05-06 14:37:13]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split('Xdebug') ../trace.php:8
0.0007 117424 -> ret_ord('X') ../trace.php:10
0.0007 117584 -> ord('X') ../trace.php:5
0.0009 117584 -> ret_ord('d') ../trace.php:10
0.0009 117584 -> ord('d') ../trace.php:5
0.0010 117584 -> ret_ord('e') ../trace.php:10
0.0011 117584 -> ord('e') ../trace.php:5
0.0012 117584 -> ret_ord('b') ../trace.php:10
0.0013 117584 -> ord('b') ../trace.php:5
0.0014 117584 -> ret_ord('u') ../trace.php:10
0.0014 117584 -> ord('u') ../trace.php:5
0.0016 117584 -> ret_ord('g') ../trace.php:10
0.0016 117584 -> ord('g') ../trace.php:5
0.0019 41152
TRACE END [2007-05-06 14:37:13]
TRACE START [2007-05-06 14:37:16]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split('Xdebug') ../trace.php:8
0.0007 117424 -> ret_ord($c = 'X') ../trace.php:10
0.0007 117584 -> ord('X') ../trace.php:5
0.0009 117584 -> ret_ord($c = 'd') ../trace.php:10
0.0009 117584 -> ord('d') ../trace.php:5
0.0010 117584 -> ret_ord($c = 'e') ../trace.php:10
0.0011 117584 -> ord('e') ../trace.php:5
0.0012 117584 -> ret_ord($c = 'b') ../trace.php:10
0.0013 117584 -> ord('b') ../trace.php:5
0.0014 117584 -> ret_ord($c = 'u') ../trace.php:10
0.0014 117584 -> ord('u') ../trace.php:5
0.0016 117584 -> ret_ord($c = 'g') ../trace.php:10
0.0016 117584 -> ord('g') ../trace.php:5
0.0019 41152
TRACE END [2007-05-06 14:37:16]
Besides the xdebug.collect_params settings there is another number of settings that affect the output of trace files. The first tab "default" shows the same as the default as above. The second tab "show_mem_delta=1" also shows the memory usage difference between two different lines in the output file.
On the "collect_return=1" tab the return values of all the function calls are also visible. This you turn on with the xdebug.collect_return setting.
The tab called "collect_assignments=1" shows variable assigments, which can be turned on with the xdebug.collect_assignments setting.
The last tab shows a different output format that is much easier to parse, but harder to read. The xdebug.trace_format setting is therefore mostly useful if there is an additional tool to interpret the trace files.
TRACE START [2007-05-06 14:37:06]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split() ../trace.php:8
0.0153 117424 -> ret_ord() ../trace.php:10
0.0165 117584 -> ord() ../trace.php:5
0.0166 117584 -> ret_ord() ../trace.php:10
0.0167 117584 -> ord() ../trace.php:5
0.0168 117584 -> ret_ord() ../trace.php:10
0.0168 117584 -> ord() ../trace.php:5
0.0170 117584 -> ret_ord() ../trace.php:10
0.0170 117584 -> ord() ../trace.php:5
0.0172 117584 -> ret_ord() ../trace.php:10
0.0172 117584 -> ord() ../trace.php:5
0.0173 117584 -> ret_ord() ../trace.php:10
0.0174 117584 -> ord() ../trace.php:5
0.0177 41152
TRACE END [2007-05-06 14:37:07]
TRACE START [2007-05-06 14:37:26]
0.0003 114112 +114112 -> {main}() ../trace.php:0
0.0004 114272 +160 -> str_split('Xdebug') ../trace.php:8
0.0007 117424 +3152 -> ret_ord($c = 'X') ../trace.php:10
0.0007 117584 +160 -> ord('X') ../trace.php:5
0.0009 117584 +0 -> ret_ord($c = 'd') ../trace.php:10
0.0009 117584 +0 -> ord('d') ../trace.php:5
0.0011 117584 +0 -> ret_ord($c = 'e') ../trace.php:10
0.0011 117584 +0 -> ord('e') ../trace.php:5
0.0013 117584 +0 -> ret_ord($c = 'b') ../trace.php:10
0.0013 117584 +0 -> ord('b') ../trace.php:5
0.0014 117584 +0 -> ret_ord($c = 'u') ../trace.php:10
0.0015 117584 +0 -> ord('u') ../trace.php:5
0.0016 117584 +0 -> ret_ord($c = 'g') ../trace.php:10
0.0017 117584 +0 -> ord('g') ../trace.php:5
0.0019 41152
TRACE END [2007-05-06 14:37:26]
TRACE START [2007-05-06 14:37:35]
0.0003 114112 -> {main}() ../trace.php:0
0.0004 114272 -> str_split('Xdebug') ../trace.php:8
>=> array (0 => 'X', 1 => 'd', 2 => 'e', 3 => 'b', 4 => 'u', 5 => 'g')
0.0007 117424 -> ret_ord($c = 'X') ../trace.php:10
0.0007 117584 -> ord('X') ../trace.php:5
>=> 88
>=> 88
0.0009 117584 -> ret_ord($c = 'd') ../trace.php:10
0.0009 117584 -> ord('d') ../trace.php:5
>=> 100
>=> 100
0.0011 117584 -> ret_ord($c = 'e') ../trace.php:10
0.0011 117584 -> ord('e') ../trace.php:5
>=> 101
>=> 101
0.0013 117584 -> ret_ord($c = 'b') ../trace.php:10
0.0013 117584 -> ord('b') ../trace.php:5
>=> 98
>=> 98
0.0015 117584 -> ret_ord($c = 'u') ../trace.php:10
0.0016 117584 -> ord('u') ../trace.php:5
>=> 117
>=> 117
0.0017 117584 -> ret_ord($c = 'g') ../trace.php:10
0.0018 117584 -> ord('g') ../trace.php:5
>=> 103
>=> 103
>=> 1
0.0021 41152
TRACE END [2007-05-06 14:37:35]
Version: 2.0.0RC4-dev
TRACE START [2007-05-06 18:29:01]
1 0 0 0.010870 114112 {main} 1 ../trace.php 0
2 1 0 0.032009 114272 str_split 0 ../trace.php 8
2 1 1 0.032073 116632
2 2 0 0.033505 117424 ret_ord 1 ../trace.php 10
3 3 0 0.033531 117584 ord 0 ../trace.php 5
3 3 1 0.033551 117584
2 2 1 0.033567 117584
2 4 0 0.033718 117584 ret_ord 1 ../trace.php 10
3 5 0 0.033740 117584 ord 0 ../trace.php 5
3 5 1 0.033758 117584
2 4 1 0.033770 117584
2 6 0 0.033914 117584 ret_ord 1 ../trace.php 10
3 7 0 0.033936 117584 ord 0 ../trace.php 5
3 7 1 0.033953 117584
2 6 1 0.033965 117584
2 8 0 0.034108 117584 ret_ord 1 ../trace.php 10
3 9 0 0.034130 117584 ord 0 ../trace.php 5
3 9 1 0.034147 117584
2 8 1 0.034160 117584
2 10 0 0.034302 117584 ret_ord 1 ../trace.php 10
3 11 0 0.034325 117584 ord 0 ../trace.php 5
3 11 1 0.034342 117584
2 10 1 0.034354 117584
2 12 0 0.034497 117584 ret_ord 1 ../trace.php 10
3 13 0 0.034519 117584 ord 0 ../trace.php 5
3 13 1 0.034536 117584
2 12 1 0.034549 117584
1 0 1 0.034636 117584
TRACE END [2007-05-06 18:29:01]
VIM syntax file
Xdebug ships with a VIM syntax file that syntax highlights the trace files: xt.vim. In order to make VIM recognise this new format you need to perform the following steps:
- Copy the xt.vim file to ~/.vim/syntax
- Edit, or create, ~/.vim/filetype.vim and add the following lines:
augroup filetypedetect au BufNewFile,BufRead *.xt setf xt augroup END
With those settings made an opened trace file looks like:
TRACE START [2007-05-15 20:06:02]
0.0003 115208 -> {main}() ../trace.php:0
0.0004 115368 -> str_split() ../trace.php:8
0.0006 118520 -> ret_ord() ../trace.php:10
0.0007 118680 -> ord() ../trace.php:5
0.0008 118680 -> ret_ord() ../trace.php:10
0.0009 118680 -> ord() ../trace.php:5
0.0010 118680 -> ret_ord() ../trace.php:10
0.0010 118680 -> ord() ../trace.php:5
0.0012 118680 -> ret_ord() ../trace.php:10
0.0012 118680 -> ord() ../trace.php:5
0.0014 118680 -> ret_ord() ../trace.php:10
0.0014 118680 -> ord() ../trace.php:5
0.0016 118680 -> ret_ord() ../trace.php:10
0.0016 118680 -> ord() ../trace.php:5
0.0019 54880
TRACE END [2007-05-15 20:06:02]
Folding also sorta works so you can use zc and zo to fold away parts of the trace files.
Related Settings
This setting, defaulting to 0, controls whether Xdebug should collect the parameters passed to functions when a function call is recorded in either the function trace or the stack trace.
The setting defaults to 0 because for very large scripts it may use huge amounts of memory and therefore make it impossible for the huge script to run. You can most safely turn this setting on, but you can expect some problems in scripts with a lot of function calls and/or huge data structures as parameters. Xdebug 2 will not have this problem with increased memory usage, as it will never store this information in memory. Instead it will only be written to disk. This means that you need to have a look at the disk usage though.
This setting can have four different values. For each of the values a different amount of information is shown. Below you will see what information each of the values provides. See also the introduction of the feature Stack Traces for a few screenshots.
| Value | Argument Information Shown |
|---|---|
| 0 | None. |
| 1 | Type and number of elements (f.e. string(6), array(8)). |
| 2 | Type and number of elements, with a tool tip for the full information 1. |
| 3 | Full variable contents (with the limits respected as set by xdebug.var_display_max_children, xdebug.var_display_max_data and xdebug.var_display_max_depth. |
| 4 | Full variable contents and variable name. |
| 5 | PHP serialized variable contents, without the name. (New in Xdebug 2.3) |
1 in the CLI version of PHP it will not have the tool tip, nor in output files.
This setting, defaulting to 0, controls whether Xdebug should write the return value of function calls to the trace files.
For computerized trace files (xdebug.trace_format=1) this only works from Xdebug 2.3 onwards.
The format of the trace file.
| Value | Description |
|---|---|
| 0 | shows a human readable indented trace file with: time index, memory usage, memory delta (if the setting xdebug.show_mem_delta is enabled), level, function name, function parameters (if the setting xdebug.collect_params is enabled), filename and line number. |
| 1 | writes a computer readable format which has two different records. There are different records for entering a stack frame, and leaving a stack frame. The table below lists the fields in each type of record. Fields are tab separated. |
| 2 | writes a trace formatted in (simple) HTML. |
Fields for the computerized format:
| Record type | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 - ... |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Entry | level | function # | always '0' | time index | memory usage | function name | user-defined (1) or internal function (0) | name of the include/require file | filename | line number | no. of parameters | parameters (as many as specified in field 11) - tab separated |
| Exit | level | function # | always '1' | time index | memory usage | empty | ||||||
| Return | level | function # | always 'R' | empty | return value | empty | ||||||
See the introduction of Function Traces for a few examples.
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:
| Specifier | Meaning | Example Format | Example Filename |
|---|---|---|---|
| %c | crc32 of the current working directory | trace.%c | trace.1258863198.xt |
| %p | pid | trace.%p | trace.5174.xt |
| %r | random number | trace.%r | trace.072db0.xt |
| %s | script name 2 | cachegrind.out.%s | cachegrind.out._home_httpd_html_test_xdebug_test_php |
| %t | timestamp (seconds) | trace.%t | trace.1179434742.xt |
| %u | timestamp (microseconds) | trace.%u | trace.1179434749_642382.xt |
| %H | $_SERVER['HTTP_HOST'] | trace.%H | trace.kossu.xt |
| %R | $_SERVER['REQUEST_URI'] | trace.%R | trace._test_xdebug_test_php_var=1_var2=2.xt |
| %U | $_SERVER['UNIQUE_ID'] 3 | trace.%U | trace.TRX4n38AAAEAAB9gBFkAAAAB.xt |
| %S | session_id (from $_COOKIE if set) | trace.%S | trace.c70c1ec2375af58f74b390bbdd2a679d.xt |
| %% | literal % | trace.%% | trace.%%.xt |
2 This one is not available for trace file names.
3 New in version 2.2. This one is set by Apache's mod_unique_id module
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 through Function Traces.
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 Remote Debugging feature.
Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or through Function Traces.
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 Remote Debugging feature.
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 through Function Traces.
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 Remote Debugging feature.
Related Functions
Returns the name of the file which is used to trace the output of this script too. This is useful when xdebug.auto_trace is enabled.
Start tracing function calls from this point to the file in the trace_file parameter. If no filename is given, then the trace file will be placed in the directory as configured by the xdebug.trace_output_dir setting.
In case a file name is given as first parameter, the name is relative to the current working directory. This current working directory might be different than you expect it to be, so please use an absolute path in case you specify a file name. Use the PHP function getcwd() to figure out what the current working directory is.
The name of the trace file is "{trace_file}.xt". If xdebug.auto_trace is enabled, then the format of the filename is "{filename}.xt" where the "{filename}" part depends on the xdebug.trace_output_name setting. The options parameter is a bitfield; currently there are three options:
- XDEBUG_TRACE_APPEND (1)
- makes the trace file open in append mode rather than overwrite mode
- XDEBUG_TRACE_COMPUTERIZED (2)
- creates a trace file with the format as described under 1 "xdebug.trace_format".
- XDEBUG_TRACE_HTML (4)
- creates a trace file as an HTML table
- XDEBUG_TRACE_NAKED_FILENAME (8)
- Normally, Xdebug always adds ".xt" to the end of the filename that you pass in as first argument to this function. With the XDEBUG_TRACE_NAKED_FILENAME flag set, ".xt" is not added. (New in Xdebug 2.3).
The full path and filename to which Xdebug traces is returned from this function. This will be either the filename you pass in (potentially with ".xt" added), or the auto generated filename if no filename has been passed in.
Stop tracing function calls and closes the trace file.
The function returns the filename of the file where the trace was written to.
Profiling PHP Scripts
Xdebug's built-in profiler allows you to find bottlenecks in your script and visualize those with an external tool such as KCacheGrind or WinCacheGrind.
Introduction
Xdebug's Profiler is a powerful tool that gives you the ability to analyze your PHP code and determine bottlenecks or generally see which parts of your code are slow and could use a speed boost. The profiler in Xdebug 2 outputs profiling information in the form of a cachegrind compatible file. This allows you to use the excellent KCacheGrind tool (Linux, KDE) to analyse your profiling data. If you are on Linux you can install KCacheGrind with your favourite package manager.
If you are on Windows, there are precompiled QCacheGrind binaries available. (QCacheGrind is KCacheGrind without KDE bindings).
If you are on Mac OSX, there are instructions on how to build QCacheGrind too.
Users of Windows can alternatively use WinCacheGrind. The functionality is different from KCacheGrind so the section that documents the use of KCacheGrind on this page doesn't apply to this program. WinCacheGrind currently does not support the file and function compression for cachegrind files that Xdebug 2.3 introduces yet.
There is also an alternative profile information presentation tool called xdebugtoolkit, a web based front-end called Webgrind, and a Java based tool called XCallGraph.
In case you can not use KDE (or do not want to use KDE) the kcachegrind package also comes with a perl script "ct_annotate" which produces ASCII output from the profiler trace files.
Starting The Profiler
Profiling is enabled by setting the xdebug.profiler_enable setting to 1 in php.ini. This instructs Xdebug to start writing profiling information into the dump directory configured with the xdebug.profiler_output_dir directive. The name of the generated file always starts with "cachegrind.out." and ends with either the PID (process ID) of the PHP (or Apache) process or the crc32 hash of the directory containing the initially debugged script. Make sure you have enough space in your xdebug.profiler_output_dir as the amount of information generated by the profiler can be enormous for complex scripts, for example up to 500MB for a complex application like eZ Publish.
You can also selectively enable the profiler with the xdebug.profiler_enable_trigger setting set to 1. If it is set to 1, then you can enable the profiler by using a GET/POST or COOKIE variable of the name XDEBUG_PROFILE. The FireFox 2 extension that can be used to enable the debugger (see HTTP Debug Sessions) can also be used with this setting. In order for the trigger to work properly, xdebug.profiler_enable needs to be set to 0.
Analysing Profiles
After a profile information file has been generated you can open it with KCacheGrind:
Once the file is opened you have plenty of information available in the
different panes of KCacheGrind. On the left side you find the "Flat Profile"
pane showing all functions in your script sorted by time spend in this function,
and all its children.
The second column "Self" shows the time spend in this function (without its
children), the third column "Called" shows how often a specific function was
called and the last column "Function" shows the name of the function. Xdebug
changes internal PHP function names by prefixing the function name with
"php::" and include files are handled in a special way too. Calls to include
(and include_one, require and require_once) are followed by "::" and the
filename of the included file. In the screenshot on the left you can see this
for "include::/home/httpd/ez_34/v..." and an example of an internal PHP
function is "php::mysql_query".
The numbers in the first two columns can be
either percentages of the full running time of the script (like in the
example) or absolute time (1 unit is 1/1.000.000th of a second). You can
switch between the two modes with the button you see on the right.
The pane on the right contains an upper and lower pane. The upper one
shows information about which functions called the current selected function
("eztemplatedesignresource->executecompiledtemplate in the screenshot).
The lower pane shows information about the functions that the current selected
function called.
The "Cost" column in the upper pane shows the time spend in the current selected function while being called from the function in the list. The numbers in the Cost column added up will always be 100%. The "Cost" column in the lower pane shows the time spend while calling the function from the list. While adding the numbers in this list up, you will most likely never reach 100% as the selected function itself will also takes time to execute.
The "All Callers" and "All Calls" tabs show not only the direct call from
which the function was called respectively all directly made
function calls but also function calls made more levels up and down.
The upper pane in the screenshot on the left shows all functions calling the
current selected one, both directly and indirectly with other functions
inbetween them on the stack. The "Distance" column shows how many function
calls are between the listed and the current selected one (-1). If there are
different distances between two functions, it is shown as a range (for example
"5-24"). The number in parentheses is the median distance. The lower pane is
similar except that it shows information on functions called from the current
selected one, again either direct or indirect.
Related Settings
.cachegrind.aggregate. You will need to move this file to get
another round of aggregate data.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.
Related Functions
Returns the name of the file which is used to save profile information to.
Remote Debugging
Xdebug provides an interface for debugger clients that interact with running PHP scripts. This section explains how to set-up PHP and Xdebug to allow this, and introduces a few clients.
Introduction
Xdebug's (remote) debugger allows you to examine data structure, interactively walk through your and debug your code. The protocol that is being used is open, and is called DBGp. This protocol is implemented in Xdebug 2, and replaces an older GDB-like protocol that is no longer supported.
Clients
Xdebug 2 is bundled with a simple command line client for the DBGp protocol. There are a few other client implementations (both free and commercial) as well. I am not the author of any of those, so please refer to the original authors for support:
- Dev-PHP (IDE: Windows)
- Eclipse plugin (IDE).
- Emacs plugin (Editor Plugin).
- KDevelop (IDE: Linux (KDE); Open Source).
- ActiveState's Komodo (IDE: Windows, Linux, Mac; Commercial).
- MacGDBP (Standalone client for Mac OS X; Free)
- NetBeans (IDE: Windows, Linux, Mac OS X and Solaris).
- Notepad++ plugin (Editor: Windows).
- WaterProof's PHPEdit (IDE, from version 2.10: Windows; Commercial).
- PHPEclipse (Editor Plugin).
- Devsense's PHP Tools for Visual Studio (MS Visual Studio Plugin; Commercial).
- JetBrain's PhpStorm (IDE; Commercial).
- Protoeditor (Editor: Linux).
- pugdebug (Standalone client for Linux, Windows and Mac OS X; Open Source).
- VIM plugin (Editor Plugin).
- jcx software's VS.Php (MS Visual Studio Plugin; Commercial).
- Xdebug Chrome App (Chrome Application; Open Source)
- XDebugClient (Standalone client for Windows).
A simple command line client for debugging is bundled with Xdebug in the
debugclient directory.
Starting The Debugger
In order to enable Xdebug's debugger you need to make some configuration settings in php.ini. These settings are xdebug.remote_enable to enable the debugger, xdebug.remote_host and xdebug.remote_port to configure the IP address and port where the debugger should connect to. There is also a xdebug.remote_connect_back setting that can be used if your development server is shared with multiple developers.
If you want the debugger to initiate a session when an error situation occurs (PHP error or exception) then you also need to change the xdebug.remote_mode setting. Allowed values for this setting are "req" (the default) which makes the debugger initiate a session as soon as a script is started, or "jit" when a session should only be initiated on an error.
After made all those settings Xdebug will still not start a debugging session automatically when a script is run. You need to activate Xdebug's debugger and you can do that in three ways:
- When running the script from the command line you need to set an
environment variable, like:
export XDEBUG_CONFIG="idekey=session_name" php myscript.php
You can also configure the xdebug.remote_host, xdebug.remote_port, xdebug.remote_mode and xdebug.remote_handler in this same environment variable as long as you separate the values by a space:export XDEBUG_CONFIG="idekey=session_name remote_host=localhost profiler_enable=1"
All settings that you can set through the XDEBUG_CONFIG setting can also be set with normal php.ini settings. - If you want to debug a script started through a web browser, simply add
XDEBUG_SESSION_START=session_nameas parameter to the URL. Instead of using a GET parameter, you can also set XDEBUG_SESSION_START as a POST parameter, or through a cookie. Refer to the next section to read on how debug sessions work from within a browser window. - An alternative way to activate the debugger while running PHP through a web
server is by installing one of the following four browser extensions. Each of
them allows you to simply enable the debugger by clicking on one button. When
these extensions are active, they set the XDEBUG_SESSION cookie directly,
instead of going through XDEBUG_SESSION_START as described in
HTTP Debug Sessions further on.
The extensions are:
- The easiest Xdebug
- This extension for Firefox was built to make debugging with an IDE easier. You can find the extension at https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/.
- Xdebug Helper for Chrome
- This extension for Chrome will help you to enable/disable debugging and profiling with a single click. You can find the extension at https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc.
- Xdebug Toggler for Safari
- This extension for Safari allows you to auto start Xdebug debugging from within Safari. You can get it from Github at https://github.com/benmatselby/xdebug-toggler.
- Xdebug launcher for Opera
- This extension for Opera allows you to start an Xdebug session from Opera.
Before you start your script you will need to tell your client that it can receive debug connections, please refer to the documentation of the specific client on how to do this. To use the bundled client simply start it after compiling and installing it. You can start it by running "debugclient".
When the debugclient starts it will show the following information and then waits until a connection is initiated 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.
After a connection is made the output of the debug server is shown:
Connect
<?xml version="1.0" encoding="iso-8859-1"?>
<init xmlns="urn:debugger_protocol_v1"
xmlns:xdebug="http://xdebug.org/dbgp/xdebug"
fileuri="file:///home/httpd/www.xdebug.org/html/docs/index.php"
language="PHP"
protocol_version="1.0"
appid="13202"
idekey="derick">
<engine version="2.0.0RC4-dev"><![CDATA[Xdebug]]></engine>
<author><![CDATA[Derick Rethans]]></author>
<url><![CDATA[http://xdebug.org]]></url>
<copyright><![CDATA[Copyright (c) 2002-2007 by Derick Rethans]]></copyright>
</init>
(cmd)
Now you can use the commandset as explained on the DBGp documentation page. When the script ends the debug server disconnects from the client and the debugclient resumes with waiting for a new connection.
Communication Set-up
With a static IP/single developer
With remote debugging, Xdebug embedded in PHP acts like the client, and the IDE as the server. The following animation shows how the communication channel is set-up:
- The IP of the server is 10.0.1.2 with HTTP on port 80
- The IDE is on IP 10.0.1.42, so xdebug.remote_host is set to 10.0.1.42
- The IDE listens on port 9000, so xdebug.remote_port is set to 9000
- The HTTP request is started on the machine running the IDE
- Xdebug connects to 10.0.1.42:9000
- Debugging runs, HTTP Response provided
With an unknown IP/multiple developers
If xdebug.remote_connect_back is used, the set-up is slightly different:
- The IP of the server is 10.0.1.2 with HTTP on port 80
- The IDE is on an unknown IP, so xdebug.remote_connect_back is set to 1
- The IDE listens on port 9000, so xdebug.remote_port is set to 9000
- The HTTP request is made, Xdebug detects the IP addres from the HTTP headers
- Xdebug connects to the detected IP (10.0.1.42) on port 9000
- Debugging runs, HTTP Response provided
HTTP Debug Sessions
Xdebug contains functionality to keep track of a debug session when started through a browser: cookies. This works like this:
- When the URL variable
XDEBUG_SESSION_START=nameis appended to an URL—or through a POST variable with the same name—Xdebug emits a cookie with the name "XDEBUG_SESSION" and as value the value of the XDEBUG_SESSION_START URL parameter. The expiry of the cookie is one hour. The DBGp protocol also passes this same value to the init packet when connecting to the debugclient in the "idekey" attribute. - When there is a GET (or POST) variable XDEBUG_SESSION_START or the XDEBUG_SESSION cookie is set, Xdebug will try to connect to a debugclient.
- To stop a debug session (and to destroy the cookie) simply add the URL
parameter
XDEBUG_SESSION_STOP. Xdebug will then no longer try to make a connection to the debugclient.
Multiple Users Debugging
Xdebug only allows you to specify one IP address to connect to with xdebug.remote_host) while doing remote debugging. It does not automatically connect back to the IP address of the machine the browser runs on, unless you use xdebug.remote_connect_back.
If all of your developers work on different projects on the same (development)
server, you can make the xdebug.remote_host setting for each directory
through Apache's .htaccess functionality by using php_value
xdebug.remote_host=10.0.0.5. However, for the case where multiple
developers work on the same code, the .htaccess trick does not work as the
directory in which the code lives is the same.
There are two solutions to this. First of all, you can use a DBGp proxy. For an overview on how to use this proxy, please refer to the article at Debugging with multiple users. You can download the proxy on ActiveState's web site as part of the python remote debugging package. There is some more documentation in the Komodo FAQ.
Secondly you can use the xdebug.remote_connect_back setting that was introduced in Xdebug 2.1.
Implementation Details
Xdebug's implementation of the
DBGp protocol's context_names
command does not depend on the stack level. The returned value is always the
same during each debugger session, and hence, can be safely cached.
Related Settings
If enabled, the xdebug.remote_host setting is ignored and Xdebug will try to connect to the client that made the HTTP request. It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out which IP address to use.
If xdebug.remote_addr_header is configured, then the $SERVER variable with the configured name will be checked before the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables.
This setting does not apply for debugging through the CLI, as the $SERVER header variables are not available there.
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.remote_host.
Can be either 'php3' which selects the old PHP 3 style debugger output, 'gdb' which enables the GDB like debugger interface or 'dbgp' - the debugger protocol. The DBGp protocol is the only supported protocol.
Note: Xdebug 2.1 and later only support 'dbgp' as protocol.
Selects the host where the debug client is running, you can either use a host name, IP address, or 'unix:///path/to/sock' for a Unix domain socket. This setting is ignored if xdebug.remote_connect_back is enabled.
Support for Unix domain sockets was introduced in Xdebug 2.6.
Log opened at 2007-05-27 14:28:15 -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/dbgp/x ... ight></init> <- step_into -i 1 -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/db ... ></response>
Selects when a debug connection is initiated. This setting can have two different values:
- req
- Xdebug will try to connect to the debug client as soon as the script starts.
- jit
- Xdebug will only try to connect to the debug client as soon as an error condition occurs.
Related Functions
This function makes the debugger break on the specific line as if a normal file/line breakpoint was set on this line.
Code Coverage Analysis
Code coverage tells you which lines of script (or set of scripts) have been executed during a request. With this information you can for example find out how good your unit tests are.
Related Settings
Related Functions
Returns whether code coverage has been started.
<?php
var_dump(xdebug_code_coverage_started());
xdebug_start_code_coverage();
var_dump(xdebug_code_coverage_started());
?>
bool(false) bool(true)
Returns a structure which contains information about which lines were executed in your script (including include files). The following example shows code coverage for one specific file:
<?php
xdebug_start_code_coverage();
function a($a) {
echo $a * 2.5;
}
function b($count) {
for ($i = 0; $i < $count; $i++) {
a($i + 0.17);
}
}
b(6);
b(10);
var_dump(xdebug_get_code_coverage());
?>
array
'/home/httpd/html/test/xdebug/docs/xdebug_get_code_coverage.php' =>
array
5 => int 1
6 => int 1
7 => int 1
9 => int 1
10 => int 1
11 => int 1
12 => int 1
13 => int 1
15 => int 1
16 => int 1
18 => int 1
This function starts gathering the information for code coverage. The information that is collected consists of an two dimensional array with as primary index the executed filename and as secondary key the line number. The value in the elements represents whether the line has been executed or whether it has unreachable lines.
The returned values for each line are:
1: this line was executed-1: this line was not executed-2: this line did not have executable code on it
-1 is only returned when the XDEBUG_CC_UNUSED
is enabled and value -2 is only returned when both
XDEBUG_CC_UNUSED and XDEBUG_CC_DEAD_CODE are enabled.
This function has two options, which act as a bitfield:
- XDEBUG_CC_UNUSED
- Enables scanning of code to figure out which line has executable code. Without this option the returned array will only have lines in them that were actually executed.
- XDEBUG_CC_DEAD_CODE
- Enables branch analyzes to figure out whether code can be executed.
You can use the options as shown in the following example.
<?php
xdebug_start_code_coverage( XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE );
?>
This function stops collecting information, the information in memory will be destroyed. If you pass "false" as argument, then the code coverage information will not be destroyed so that you can resume the gathering of information with the xdebug_start_code_coverage() function again.
FAQ
Frequently Asked Questions
Using Xdebug
- Q: phpinfo() reports that Xdebug is installed and enabled, yet I still don't get any stacktraces when an error happens.
- A1: You have to search through all your PHP libraries and include files for any "set_error_handler" calls. If there are any, you have to either comment it out, or change the body of the handler function to call xdebug_* api functions.
- A2: You do not have set display_errors to 1 in php.ini
- Q: Xdebug doesn't format output.
- A: Make sure you have PHP's html_errors set to 1 in php.ini
- Q: The debug client doesn't receive any connections, what do I do wrong?
- A: You probably forgot to set the environment variable or to add the necessary information to your URL. See the documentation for more information.
- A: Have you checked your firewall settings? Make sure the port Xdebug is listening on (default 9000) is not blocked.
- A: Are you using FastCGI, maybe via FPM (FastCGI Process Manager)? It uses the same port by default as Xdebug (9000) so you will need to change one of them to a different number. In Xdebug you can do that with xdebug.remote_port.
- A: If you are running with SELinux you should make sure it is not
preventing connections; look for warnings about
name_connector anything related to the Xdebug port. You might have to allow access explicitly. Visit this site or search for "selinux name_connect apache" for more information about how to do this
Compilation and Configuration
-
Q: I don't have the
phpizetool. - A: Debian and Ubuntu users need to install the PHP development package with
apt install php5-dev, orapt install php7.0-devfor PHP 7. - Q: What to do with: Xdebug requires Zend Engine API version xxxxxxxx. The Zend Engine API version 2xxxxxxxx which is installed, is newer.
- A: This message means that you are trying to load Xdebug with a PHP version for which it wasn't built. If you compiled PHP yourself, it is most likely because you compiled Xdebug against PHP headers that belong to a different PHP version that you're running. For example, you're using PHP 5.3 and the headers you're using are still PHP 5.2. If you are using a pre-compiled binary, then you're using the wrong one.
- To diagnose if this is your problem, make the following steps:
- Check what the "Zend Extension" API number is of the PHP version that you are running by looking at phpinfo() (or "php -i") output. You can find it in the top part of the output, in the same block as the PHP logo and the PHP version. As examples, for PHP 5.2, the number is "220060519" and for PHP 5.3 it is "220090626".
- Check what the output of "phpize" is when you're completing the compilation steps. The number that you're looking for is on the line that says "Zend Extension Api No".
If the two numbers from above do not match, you're compiling with the wrong PHP headers. Refer to the next FAQ entry to figure out which phpize to use.
- Q: Xdebug is only loaded as PHP extension and not as a Zend Extension.
-
The tailored installation intstructions might have you pointed to this entry.
In order for Xdebug to work properly, including breakpoints etc. it is required that it is loaded as a Zend extension, and not just as a normal PHP extension. Some installation tools (PEAR/PECL) sometimes advice you to use
extension=xdebug.soto load Xdebug. This is not correct. In order to fix this issue, please look for a lineextension=xdebug.soin any of the INI files that are listed under "Loaded Configuration File" and "Additional .ini files parsed" in the top block. Remove this line, and go back to the Tailored Installation Instructions. - Q: How do I find which phpize to use?
- A:
Run: "phpize --help". This shows you the full path to
phpize. This path should be the same as where you have the CLI binary,
"php-config" and the "pear" and "pecl" binaries installed. If you
run "php-config --version" it should show the same version of PHP that
you're running. If it doesn't match up, and perhaps the wrong "phpize"
binary is found on the path, you can run configure as follows:
- /full/path/to/php/bin/phpize
- ./configure --with-php-config=/full/path/to/php/bin/php-config
- Q: I'm using XAMPP, but I can't seem to get the packaged xdebug extension to work properly.
- A: If you uncommented the "extension=php_xdebug.dll" line, that is to be expected. Xdebug needs to be loaded with the zend_extension_ts= "C:\path\to\php_xdebug.dll" directive. You'll also likely have to disable the loading of the Zend Optimizer, since it's enabled by default, and doesn't work well with Xdebug. So look for the related entry in php.ini, and comment it out. From PHP 5.3 onwards, you always need to use the zend_extension PHP.ini setting name, and not zend_extension_ts.
- Q: On Debian, I am seeing the following problem with the build of
Xdebug.... any fixes?
/usr/lib/libc_nonshared.a(stat.oS)(.text.__i686.get_pc_thunk.bx+0x0): In function `__i686.get_pc_thunk.bx': : multiple definition of `__i686.get_pc_thunk.bx' /usr/lib/gcc-lib/i486-linux/3.3.5/crtbeginS.o (.gnu.linkonce.t.__i686.get_pc_thunk.bx+0x0): first defined here collect2: ld returned 1 exit status make: *** [xdebug.la] Error 1
- A: This is an issue with Debian itself, see for more information here and here.
Reference
Related Settings
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, defaulting to 0, controls whether Xdebug should collect the parameters passed to functions when a function call is recorded in either the function trace or the stack trace.
The setting defaults to 0 because for very large scripts it may use huge amounts of memory and therefore make it impossible for the huge script to run. You can most safely turn this setting on, but you can expect some problems in scripts with a lot of function calls and/or huge data structures as parameters. Xdebug 2 will not have this problem with increased memory usage, as it will never store this information in memory. Instead it will only be written to disk. This means that you need to have a look at the disk usage though.
This setting can have four different values. For each of the values a different amount of information is shown. Below you will see what information each of the values provides. See also the introduction of the feature Stack Traces for a few screenshots.
| Value | Argument Information Shown |
|---|---|
| 0 | None. |
| 1 | Type and number of elements (f.e. string(6), array(8)). |
| 2 | Type and number of elements, with a tool tip for the full information 1. |
| 3 | Full variable contents (with the limits respected as set by xdebug.var_display_max_children, xdebug.var_display_max_data and xdebug.var_display_max_depth. |
| 4 | Full variable contents and variable name. |
| 5 | PHP serialized variable contents, without the name. (New in Xdebug 2.3) |
1 in the CLI version of PHP it will not have the tool tip, nor in output files.
This setting, defaulting to 0, controls whether Xdebug should write the return value of function calls to the trace files.
For computerized trace files (xdebug.trace_format=1) this only works from Xdebug 2.3 onwards.
* 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 seperated list of
variables from this superglobal to dump, or * for all of them.
Make sure you do not add spaces in this setting.
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 = *
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:
| Specifier | Meaning |
|---|---|
| %f | the filename |
| %l | the line number |
For various IDEs/OSses there are some instructions listed on how to make this work:
Firefox on Linux
- Open about:config
- Add a new boolean setting "network.protocol-handler.expose.xdebug" and set it to "false"
- Add the following into a shell script
~/bin/ff-xdebug.sh:#! /bin/sh f=`echo $1 | cut -d @ -f 1 | sed 's/xdebug:\/\///'` l=`echo $1 | cut -d @ -f 2`
Add to that one of (depending whether you have komodo, gvim or netbeans):komodo $f -l $lgvim --remote-tab +$l $fnetbeans "$f:$l"
- Make the script executable with
chmod +x ~/bin/ff-xdebug.sh - Set the xdebug.file_link_format setting to
xdebug://%f@%l
Windows and netbeans
- Create the file
netbeans.batand save it in your path (C:\Windowswill work):@echo off setlocal enableextensions enabledelayedexpansion set NETBEANS=%1 set FILE=%~2 %NETBEANS% --nosplash --console suppress --open "%FILE:~19%" nircmd win activate process netbeans.exe
Note: Remove the last line if you don't have
nircmd. - Save the following code as
netbeans_protocol.reg:Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\netbeans] "URL Protocol"="" @="URL:Netbeans Protocol" [HKEY_CLASSES_ROOT\netbeans\DefaultIcon] @="\"C:\\Program Files\\NetBeans 7.1.1\\bin\\netbeans.exe,1\"" [HKEY_CLASSES_ROOT\netbeans\shell] [HKEY_CLASSES_ROOT\netbeans\shell\open] [HKEY_CLASSES_ROOT\netbeans\shell\open\command] @="\"C:\\Windows\\netbeans.bat\" \"C:\\Program Files\\NetBeans 7.1.1\\bin\\netbeans.exe\" \"%1\""
Note: Make sure to change the path to Netbeans (twice), as well as the
netbeans.batbatch file if you saved it somewhere else thanC:\Windows\. - Double click on the
netbeans_protocol.regfile to import it into the registry. - Set the xdebug.file_link_format setting to
xdebug.file_link_format = "netbeans://open/?f=%f:%l"
If this setting is set to 1 then errors will
always be displayed, no matter what the setting of PHP's display_errors
is.
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().
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. echo "Hi!\n"; will not be executed.
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.
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.
Before Xdebug 2.3, the default value was 100.
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.
By default Xdebug overloads var_dump() with its own improved version
for displaying variables when the html_errors php.ini setting is set to
1 or 2. In case you do not want that, you can
set this setting to 0, but check first if it's not smarter
to turn off html_errors.
You can also use 2 as value for this setting. Besides
formatting the var_dump() output nicely, it will also add filename and
line number to the output. The xdebug.file_link_format setting is also
respected. (New in Xdebug 2.3)
Before Xdebug 2.4, the default value of this setting was
1.
.cachegrind.aggregate. You will need to move this file to get
another round of aggregate data.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.
If enabled, the xdebug.remote_host setting is ignored and Xdebug will try to connect to the client that made the HTTP request. It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out which IP address to use.
If xdebug.remote_addr_header is configured, then the $SERVER variable with the configured name will be checked before the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables.
This setting does not apply for debugging through the CLI, as the $SERVER header variables are not available there.
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.remote_host.
Can be either 'php3' which selects the old PHP 3 style debugger output, 'gdb' which enables the GDB like debugger interface or 'dbgp' - the debugger protocol. The DBGp protocol is the only supported protocol.
Note: Xdebug 2.1 and later only support 'dbgp' as protocol.
Selects the host where the debug client is running, you can either use a host name, IP address, or 'unix:///path/to/sock' for a Unix domain socket. This setting is ignored if xdebug.remote_connect_back is enabled.
Support for Unix domain sockets was introduced in Xdebug 2.6.
Log opened at 2007-05-27 14:28:15 -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/dbgp/x ... ight></init> <- step_into -i 1 -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="http://xdebug.org/db ... ></response>
Selects when a debug connection is initiated. This setting can have two different values:
- req
- Xdebug will try to connect to the debug client as soon as the script starts.
- jit
- Xdebug will only try to connect to the debug client as soon as an error condition occurs.
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.
The format of the trace file.
| Value | Description |
|---|---|
| 0 | shows a human readable indented trace file with: time index, memory usage, memory delta (if the setting xdebug.show_mem_delta is enabled), level, function name, function parameters (if the setting xdebug.collect_params is enabled), filename and line number. |
| 1 | writes a computer readable format which has two different records. There are different records for entering a stack frame, and leaving a stack frame. The table below lists the fields in each type of record. Fields are tab separated. |
| 2 | writes a trace formatted in (simple) HTML. |
Fields for the computerized format:
| Record type | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 - ... |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Entry | level | function # | always '0' | time index | memory usage | function name | user-defined (1) or internal function (0) | name of the include/require file | filename | line number | no. of parameters | parameters (as many as specified in field 11) - tab separated |
| Exit | level | function # | always '1' | time index | memory usage | empty | ||||||
| Return | level | function # | always 'R' | empty | return value | empty | ||||||
See the introduction of Function Traces for a few examples.
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:
| Specifier | Meaning | Example Format | Example Filename |
|---|---|---|---|
| %c | crc32 of the current working directory | trace.%c | trace.1258863198.xt |
| %p | pid | trace.%p | trace.5174.xt |
| %r | random number | trace.%r | trace.072db0.xt |
| %s | script name 2 | cachegrind.out.%s | cachegrind.out._home_httpd_html_test_xdebug_test_php |
| %t | timestamp (seconds) | trace.%t | trace.1179434742.xt |
| %u | timestamp (microseconds) | trace.%u | trace.1179434749_642382.xt |
| %H | $_SERVER['HTTP_HOST'] | trace.%H | trace.kossu.xt |
| %R | $_SERVER['REQUEST_URI'] | trace.%R | trace._test_xdebug_test_php_var=1_var2=2.xt |
| %U | $_SERVER['UNIQUE_ID'] 3 | trace.%U | trace.TRX4n38AAAEAAB9gBFkAAAAB.xt |
| %S | session_id (from $_COOKIE if set) | trace.%S | trace.c70c1ec2375af58f74b390bbdd2a679d.xt |
| %% | literal % | trace.%% | trace.%%.xt |
2 This one is not available for trace file names.
3 New in version 2.2. This one is set by Apache's mod_unique_id module
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 through Function Traces.
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 Remote Debugging feature.
Controls the maximum string length that is shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or through Function Traces.
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 Remote Debugging feature.
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 through Function Traces.
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 Remote Debugging feature.
Related Functions
This function is overloaded by Xdebug, see the description for xdebug_var_dump().
This function makes the debugger break on the specific line as if a normal file/line breakpoint was set on this line.
NULL if the stack frame does not exist, or FALSE if the stack frame has no class information
This function returns the name of the class that defined the current method, or
FALSE if no class is associated with this call.
<?php
class Strings
{
static function fix_string($a)
{
echo
xdebug_call_class().
"::".
xdebug_call_function().
" is called at ".
xdebug_call_file().
":".
xdebug_call_line();
}
}
$ret = Strings::fix_string( 'Derick' );
?>
Called @ /home/httpd/html/test/xdebug_caller.php:17 from ::{main}
To retrieve information from earlier stack frames, use the optional
$depth argument. A value of 1 returns
the call information of the method that executed xdebug_call_class():
<?php
class Strings
{
static function fix_string( $a )
{
echo
xdebug_call_class( 1 ).
"::".
xdebug_call_function( 1 ).
" is called at ".
xdebug_call_file( 1 ).
":".
xdebug_call_line( 1 );
}
}
$ret = Strings::fix_string( 'Derick' );
?>
Strings::fix_string is called at /home/httpd/html/test/xdebug_caller:17
A value of 2 (the default) returns the call information of the
"grand parent" of the current method:
<?php
class Strings
{
static function fix_string( $a )
{
echo
xdebug_call_class( 2 ).
"::".
xdebug_call_function( 2 ).
" is called at ".
xdebug_call_file( 2 ).
":".
xdebug_call_line( 2 );
}
static function fix_strings( array $a )
{
foreach ( $a as $element )
{
self::fix_string( $a );
}
}
}
$ret = Strings::fix_strings( [ 'Derick' ] );
?>
Strings::fix_strings is called at /home/httpd/html/test/xdebug_caller:25
A value of 0 returns the call information of the call to
corresponding xdebug_call_* method:
<?php
class Strings
{
static function fix_string( $a )
{
echo
xdebug_call_class( 0 ).
"::".
xdebug_call_function( 0 ).
" is called at ".
xdebug_call_file( 0 ).
":".
xdebug_call_line( 0 );
}
static function fix_strings( array $a )
{
foreach ( $a as $element )
{
self::fix_string( $a );
}
}
}
$ret = Strings::fix_strings( [ 'Derick' ] );
?>
::xdebug_call_function is called at /home/httpd/html/test/xdebug_caller:13
NULL if the stack frame does not existThis function returns the filename from where the current function/method was executed from.
To retrieve information from earlier stack frames, use the optional
$depth argument.
For examples and more extensive information, see xdebug_call_class().
NULL if the stack frame does not exist, or FALSE if the stack frame has no function/method informationThis function returns the name of the current function/method.
To retrieve information from earlier stack frames, use the optional
$depth argument.
For examples and more extensive information, see xdebug_call_class().
NULL if the stack frame does not existThis function returns the line number from where the current function/method was called from.
To retrieve information from earlier stack frames, use the optional
$depth argument.
For examples and more extensive information, see xdebug_call_class().
Returns whether code coverage has been started.
<?php
var_dump(xdebug_code_coverage_started());
xdebug_start_code_coverage();
var_dump(xdebug_code_coverage_started());
?>
bool(false) bool(true)
This function displays structured information about one or more variables that includes its type, value and refcount information. Arrays are explored recursively with values. This function is implemented differently from PHP's debug_zval_dump() function in order to work around the problems that that function has because the variable itself is actually passed to the function. Xdebug's version is better as it uses the variable name to lookup the variable in the internal symbol table and accesses all the properties directly without having to deal with actually passing a variable to a function. The result is that the information that this function returns is much more accurate than PHP's own function for showing zval information.
Support for anything but simple variable names (such as "a[2]" below) is supported since Xdebug 2.3.
<?php
$a = array(1, 2, 3);
$b =& $a;
$c =& $a[2];
xdebug_debug_zval('a');
xdebug_debug_zval("a[2]");
?>
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)=1, 1 => (refcount=1, is_ref=0)=2, 2 => (refcount=2, is_ref=1)=3) a[2]: (refcount=2, is_ref=1)=3
This function displays structured information about one or more variables that includes its type, value and refcount information. Arrays are explored recursively with values. The difference with xdebug_debug_zval() is that the information is not displayed through a web server API layer, but directly shown on stdout (so that when you run it with Apache in single process mode it ends up on the console).
<?php
$a = array(1, 2, 3);
$b =& $a;
$c =& $a[2];
xdebug_debug_zval_stdout('a');
a: (refcount=2, is_ref=1)=array ( 0 => (refcount=1, is_ref=0)=1, 1 => (refcount=1, is_ref=0)=2, 2 => (refcount=2, is_ref=1)=3)
Disable showing stack traces on error conditions.
This function dumps the values of the elements of the super globals as specified with the xdebug.dump.* php.ini settings. For the example below the settings in php.ini are:
xdebug.dump.GET=*
xdebug.dump.SERVER=REMOTE_ADDR
Query string:
?var=fourty%20two&array[a]=a&array[9]=b
| Dump $_SERVER | ||||
|---|---|---|---|---|
$_SERVER['REMOTE_ADDR'] = | string '127.0.0.1' (length=9) | |||
| Dump $_GET | ||||
$_GET['var'] = | string 'fourty two' (length=10) | |||
$_GET['array'] = | array 'a' => string 'a' (length=1) 9 => string 'b' (length=1) | |||
Enable showing stack traces on error conditions.
Returns a structure which contains information about which lines were executed in your script (including include files). The following example shows code coverage for one specific file:
<?php
xdebug_start_code_coverage();
function a($a) {
echo $a * 2.5;
}
function b($count) {
for ($i = 0; $i < $count; $i++) {
a($i + 0.17);
}
}
b(6);
b(10);
var_dump(xdebug_get_code_coverage());
?>
array
'/home/httpd/html/test/xdebug/docs/xdebug_get_code_coverage.php' =>
array
5 => int 1
6 => int 1
7 => int 1
9 => int 1
10 => int 1
11 => int 1
12 => int 1
13 => int 1
15 => int 1
16 => int 1
18 => int 1
This function returns all errors from the collection buffer that contains all errors that were stored there when error collection was started with xdebug_start_error_collection().
By default this function will not clear the error collection buffer. If you pass
This function returns a string containing all collected errors formatted as an "Xdebug table".
Returns an array where each element is a variable name which is defined in the current scope. The setting xdebug.collect_vars needs to be enabled.
<?php
class strings {
static function fix_strings($a, $b) {
foreach ($b as $item) {
}
var_dump(xdebug_get_declared_vars());
}
}
strings::fix_strings(array(1,2,3), array(4,5,6));
?>
array 0 => string 'a' (length=1) 1 => string 'b' (length=1) 2 => string 'item' (length=4)
In PHP versions before 5.1, the variable name "a" is not in the returned array, as it is not used in the scope where the function xdebug_get_declared_vars() is called in.
Returns an array which resembles the stack trace up to this point. The example script:
<?php
class strings {
function fix_string($a)
{
var_dump(xdebug_get_function_stack());
}
function fix_strings($b) {
foreach ($b as $item) {
$this->fix_string($item);
}
}
}
$s = new strings();
$ret = $s->fix_strings(array('Derick'));
?>
array
0 =>
array
'function' => string '{main}' (length=6)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 0
'params' =>
array
empty
1 =>
array
'function' => string 'fix_strings' (length=11)
'class' => string 'strings' (length=7)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 18
'params' =>
array
'b' => string 'array (0 => 'Derick')' (length=21)
2 =>
array
'function' => string 'fix_string' (length=10)
'class' => string 'strings' (length=7)
'file' => string '/var/www/xdebug_get_function_stack.php' (length=63)
'line' => int 12
'params' =>
array
'a' => string ''Derick'' (length=8)
Returns all the headers that are set with PHP's header() function, or any other header set internally within PHP (such as through setcookie()), as an array.
<?php
header( "X-Test", "Testing" );
setcookie( "TestCookie", "test-value" );
var_dump( xdebug_get_headers() );
?>
array(2) {
[0]=>
string(6) "X-Test"
[1]=>
string(33) "Set-Cookie: TestCookie=test-value"
}
Returns a structure which contains information about where the monitored functions were executed in your script. The following example shows how to use this, and the returned information:
<?php
/* Start the function monitor for strrev and array_push: */
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );
/* Run some code: */
echo strrev("yes!"), "\n";
echo strrev("yes!"), "\n";
var_dump(xdebug_get_monitored_functions());
xdebug_stop_function_monitor();
?>
/tmp/monitor-example.php:10:
array(2) {
[0] =>
array(3) {
'function' =>
string(6) "strrev"
'filename' =>
string(24) "/tmp/monitor-example.php"
'lineno' =>
int(6)
}
[1] =>
array(3) {
'function' =>
string(6) "strrev"
'filename' =>
string(24) "/tmp/monitor-example.php"
'lineno' =>
int(8)
}
}
Returns the name of the file which is used to save profile information to.
Returns the stack depth level. The main body of a script is level 0 and each include and/or function call adds one to the stack depth level.
Returns the name of the file which is used to trace the output of this script too. This is useful when xdebug.auto_trace is enabled.
Return whether stack traces would be shown in case of an error or not.
Returns the current amount of memory the script uses. Before PHP 5.2.1, this only works if PHP is compiled with --enable-memory-limit. From PHP 5.2.1 and later this function is always available.
Returns the maximum amount of memory the script used until now. Before PHP 5.2.1, this only works if PHP is compiled with --enable-memory-limit. From PHP 5.2.1 and later this function is always available.
Displays the current function stack, in a similar way as what Xdebug would display in an error situation.
The "message" argument allows you to replace the message in the header with your own. (Introduced in Xdebug 2.1).
<?php
function foo( $far, $out )
{
xdebug_print_function_stack( 'Your own message' );
}
foo( 42, 3141592654 );
?>
( ! ) Xdebug: Your own message in /home/httpd/html/test/xdebug/print_function_stack.php on line 5 Call Stack # Time Memory Function Location 1 0.0006 653896 {main}( ) ../print_function_stack.php:0 2 0.0007 654616 foo( 42, 3141592654 ) ../print_function_stack.php:7 3 0.0007 654736 xdebug_print_function_stack ( 'Your own message' ) ../print_function_stack.php:5
The bitmask "options" allows you to configure a few extra options. The following options are currently supported:
XDEBUG_STACK_NO_DESC- If this option is set, then the printed stack trace will not have a
header. This is useful if you want to print a stack trace from your own error
handler, as otherwise the printed location is where
xdebug_print_function_stack()was called from. (Introduced in Xdebug 2.3).
This function starts gathering the information for code coverage. The information that is collected consists of an two dimensional array with as primary index the executed filename and as secondary key the line number. The value in the elements represents whether the line has been executed or whether it has unreachable lines.
The returned values for each line are:
1: this line was executed-1: this line was not executed-2: this line did not have executable code on it
-1 is only returned when the XDEBUG_CC_UNUSED
is enabled and value -2 is only returned when both
XDEBUG_CC_UNUSED and XDEBUG_CC_DEAD_CODE are enabled.
This function has two options, which act as a bitfield:
- XDEBUG_CC_UNUSED
- Enables scanning of code to figure out which line has executable code. Without this option the returned array will only have lines in them that were actually executed.
- XDEBUG_CC_DEAD_CODE
- Enables branch analyzes to figure out whether code can be executed.
You can use the options as shown in the following example.
<?php
xdebug_start_code_coverage( XDEBUG_CC_UNUSED | XDEBUG_CC_DEAD_CODE );
?>
When this function is executed, Xdebug will cause PHP not to display any notices, warnings or errors. Instead, they are formatted according to Xdebug's normal error formatting rules (ie, the error table with the red exclamation mark) and then stored in a buffer. This will continue until you call xdebug_stop_error_collection().
This buffer's contents can be retrieved by calling xdebug_get_collected_errors() and then subsequently displayed. This is really useful if you want to prevent Xdebug's powerful error reporting features from destroying your layout.
This function starts the monitoring of functions that were given in a list as argument to this function. Function monitoring allows you to find out where in your code the functions that you provided as argument are called from. This can be used to track where old, or, discouraged functions are used.
<?php
xdebug_start_function_monitor( [ 'strrev', 'array_push' ] );
?>
You can also add class methods and static methods to the array that defines which functions to monitor. For example, to catch static calls to DramModel::canSee and dynamic calls to Whisky->drink, you would start the monitor with:
<?php
xdebug_start_function_monitor( [ 'DramModel::canSee', 'Whisky->drink'] );
?>
The defined functions are case sensitive, and a dynamic call to a static method will not be caught.
Start tracing function calls from this point to the file in the trace_file parameter. If no filename is given, then the trace file will be placed in the directory as configured by the xdebug.trace_output_dir setting.
In case a file name is given as first parameter, the name is relative to the current working directory. This current working directory might be different than you expect it to be, so please use an absolute path in case you specify a file name. Use the PHP function getcwd() to figure out what the current working directory is.
The name of the trace file is "{trace_file}.xt". If xdebug.auto_trace is enabled, then the format of the filename is "{filename}.xt" where the "{filename}" part depends on the xdebug.trace_output_name setting. The options parameter is a bitfield; currently there are three options:
- XDEBUG_TRACE_APPEND (1)
- makes the trace file open in append mode rather than overwrite mode
- XDEBUG_TRACE_COMPUTERIZED (2)
- creates a trace file with the format as described under 1 "xdebug.trace_format".
- XDEBUG_TRACE_HTML (4)
- creates a trace file as an HTML table
- XDEBUG_TRACE_NAKED_FILENAME (8)
- Normally, Xdebug always adds ".xt" to the end of the filename that you pass in as first argument to this function. With the XDEBUG_TRACE_NAKED_FILENAME flag set, ".xt" is not added. (New in Xdebug 2.3).
The full path and filename to which Xdebug traces is returned from this function. This will be either the filename you pass in (potentially with ".xt" added), or the auto generated filename if no filename has been passed in.
This function stops collecting information, the information in memory will be destroyed. If you pass "false" as argument, then the code coverage information will not be destroyed so that you can resume the gathering of information with the xdebug_start_code_coverage() function again.
When this function is executed, error collection as started by xdebug_start_error_collection() is aborted. The errors stored in the collection buffer are not deleted and still available to be fetched through xdebug_get_collected_errors().
This function stops the function monitor. In order to get the list of monitored functions, you need to use the xdebug_get_monitored_functions() function.
Stop tracing function calls and closes the trace file.
The function returns the filename of the file where the trace was written to.
Returns the current time index since the starting of the script in seconds.
<?php
echo xdebug_time_index(), "\n";
for ($i = 0; $i < 250000; $i++)
{
// do nothing
}
echo xdebug_time_index(), "\n";
?>
0.00038003921508789 0.76580691337585
This function displays structured information about one or more expressions that includes its type and value. Arrays are explored recursively with values. See the introduction of Variable Display Features on which php.ini settings affect this function.
<?php
ini_set('xdebug.var_display_max_children', 3 );
$c = new stdClass;
$c->foo = 'bar';
$c->file = fopen( '/etc/passwd', 'r' );
var_dump(
array(
array(TRUE, 2, 3.14, 'foo'),
'object' => $c
)
);
?>
array
0 =>
array
0 => boolean true
1 => int 2
2 => float 3.14
more elements...
'object' =>
object(stdClass)[1]
public 'foo' => string 'bar' (length=3)
public 'file' => resource(3, stream)
All rights reserved.