XDEBUG EXTENSION FOR PHP | DOCUMENTATION

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 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:

  1. 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.
  2. cd xdebug-2.2.5
  3. 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.
  4. ./configure --enable-xdebug
  5. make
  6. make install

Configure PHP to Use Xdebug

  1. add the following line to php.ini: zend_extension="/wherever/you/put/it/xdebug.so" (for non-threaded use of PHP, for example the CLI, CGI or Apache 1.3 module) or: zend_extension_ts="/wherever/you/put/it/xdebug.so" (for threaded usage of PHP, for example the Apache 2 work MPM or the the ISAPI module). Note: In case you compiled PHP yourself and used --enable-debug you would have to use zend_extension_debug=. 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.
  2. Restart your webserver.
  3. 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(05),
);
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


xdebug.cli_color
Type: integer, Default value: 0, Introduced in Xdebug > 2.2

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.


xdebug.overload_var_dump
Type: boolean, Default value: 1, Introduced in Xdebug > 2.1

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. 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)


xdebug.var_display_max_children
Type: integer, Default value: 128

Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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.


xdebug.var_display_max_data
Type: integer, Default value: 512

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.


xdebug.var_display_max_depth
Type: integer, Default value: 3

Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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


void var_dump( [mixed var [, ...]] )
Displays detailed information about a variable

This function is overloaded by Xdebug, see the description for xdebug_var_dump().


void xdebug_debug_zval( [string varname [, ...]] )
Displays information about a variable

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.

Example:

<?php
    $a 
= array(123);
    
$b =& $a;
    
$c =& $a[2];

    
xdebug_debug_zval('a');
    
xdebug_debug_zval("a[2]");
?>

Returns:

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

void xdebug_debug_zval_stdout( [string varname [, ...]] )
Returns information about variables to stdout.

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).

Example:

<?php
    $a 
= array(123);
    
$b =& $a;
    
$c =& $a[2];

    
xdebug_debug_zval_stdout('a');

Returns:

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)

void xdebug_dump_superglobals()
Displays information about super globals

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:

Example:

xdebug.dump.GET=*
xdebug.dump.SERVER=REMOTE_ADDR

Query string:
?var=fourty%20two&array[a]=a&array[9]=b

Returns:

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)

void xdebug_var_dump( [mixed var [, ...]] )
Displays detailed information about a variable

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.

Example:

<?php
ini_set
('xdebug.var_display_max_children');
$c = new stdClass;
$c->foo 'bar';
$c->file fopen'/etc/passwd''r' );
var_dump(
    array(
        array(
TRUE23.14'foo'),
        
'object' => $c
    
)
);
?>  

Returns:

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 == 500000xdebug_break();
    }
}

set_time_limit(1);
$c = new stdClass;
$c->bar 100;
$a = array(
    
42 => false'foo' => 912124,
    
$c, new stdClassfopen'/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
#TimeMemoryFunctionLocation
10.000158564{main}( )../stack.php:0
20.000462764foo( )../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
#TimeMemoryFunctionLocation
10.000158132{main}( )../stack.php:0
20.000462380foo( 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
#TimeMemoryFunctionLocation
10.000158564{main}( )../stack.php:0
20.000462812foo( 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
#TimeMemoryFunctionLocation
10.000158564{main}( )../stack.php:0
20.000462812foo( 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
#TimeMemoryFunctionLocation
10.000158132{main}( )../stack.php:0
20.000462380foo( $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
#TimeMemoryFunctionLocation
10.000158564{main}( )../stack.php:0
20.000462764foo( )../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
#TimeMemoryFunctionLocation
10.000158132{main}( )../stack.php:0
20.000462436foo( )../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
#TimeMemoryFunctionLocation
10.000158132{main}( )../stack.php:0
20.000562588foo( )../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


xdebug.cli_color
Type: integer, Default value: 0, Introduced in Xdebug > 2.2

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.


xdebug.collect_includes
Type: boolean, Default value: 1
This setting, defaulting to 1, controls whether Xdebug should write the filename used in include(), include_once(), require() or require_once() to the trace files.

xdebug.collect_params
Type: integer, Default value: 0

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.

ValueArgument Information Shown
0None.
1Type 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.

3Full 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.
4Full variable contents and variable name.
5PHP 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.


xdebug.collect_vars
Type: boolean, Default value: 0
This setting tells Xdebug to gather information about which variables are used in a certain scope. This analysis can be quite slow as Xdebug has to reverse engineer PHP's opcode arrays. This setting will not record which values the different variables have, for that use xdebug.collect_params. This setting needs to be enabled only if you wish to use xdebug_get_declared_vars().

xdebug.dump.*
Type: string, Default value: Empty

* can be any of COOKIE, FILES, GET, POST, REQUEST, SERVER, SESSION. These seven settings control which data from the superglobals is shown when an error situation occurs.

Each of those php.ini setting can consist of a comma 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 = *

xdebug.dump_globals
Type: boolean, Default value: 1
Controls whether the values of the superglobals as defined by the xdebug.dump.* settings should be shown or not.

xdebug.dump_once
Type: boolean, Default value: 1
Controls whether the values of the superglobals should be dumped on all error situations (set to 0) or only on the first (set to 1).

xdebug.dump_undefined
Type: boolean, Default value: 0
If you want to dump undefined values from the superglobals you should set this setting to 1, otherwise leave it set to 0.

xdebug.file_link_format
Type: string, Default value: , Introduced in Xdebug > 2.1

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:

SpecifierMeaning
%fthe filename
%lthe 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"
  • 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 or gvim):
    • komodo $f -l $l
    • gvim --remote-tab +$l $f
  • 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.bat and save it in your path (C:\Windows will 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.bat batch file if you saved it somewhere else than C:\Windows\.

  • Double click on the netbeans_protocol.reg file to import it into the registry.
  • Set the xdebug.file_link_format setting to xdebug.file_link_format = "netbeans://open/?f=%f:%l"

xdebug.manual_url
Type: string, Default value: http://www.php.net, Introduced in Xdebug < 2.2.1
This is the base url for the links from the function traces and error message to the manual pages of the function from the message. It is advisable to set this setting to use the closest mirror.

xdebug.show_exception_trace
Type: integer, Default value: 0
When this setting is set to 1, Xdebug will show a stack trace whenever an exception is raised - even if this exception is actually caught.

xdebug.show_local_vars
Type: integer, Default value: 0
When this setting is set to something != 0 Xdebug's generated stack dumps in error situations will also show all variables in the top-most scope. Beware that this might generate a lot of information, and is therefore turned off by default.

xdebug.show_mem_delta
Type: integer, Default value: 0
When this setting is set to something != 0 Xdebug's human-readable generated trace files will show the difference in memory usage between function calls. If Xdebug is configured to generate computer-readable trace files then they will always show this information.

xdebug.var_display_max_children
Type: integer, Default value: 128

Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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.


xdebug.var_display_max_data
Type: integer, Default value: 512

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.


xdebug.var_display_max_depth
Type: integer, Default value: 3

Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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


array xdebug_get_declared_vars()
Returns declared variables

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.

Example:

<?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));
?>

Returns:

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.


array xdebug_get_function_stack()
Returns information about the stack

Returns an array which resembles the stack trace up to this point. The example script:

Example:

<?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'));
?>

Returns:

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)


integer xdebug_get_stack_depth()
Returns the current stack depth level

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.


none xdebug_print_function_stack( [ string message [, int options ] ] )
Displays the current function stack.

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).

Example:

<?php
function foo$far$out )
{
    
xdebug_print_function_stack'Your own message' );
}
foo423141592654 );
?>

Returns:

( ! ) Xdebug: Your own message in /home/httpd/html/test/xdebug/print_function_stack.php on line 5
Call Stack
#TimeMemoryFunctionLocation
10.0006653896{main}( )../print_function_stack.php:0
20.0007654616foo( 42, 3141592654 )../print_function_stack.php:7
30.0007654736xdebug_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).


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:

  1. Copy the xt.vim file to ~/.vim/syntax
  2. 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


xdebug.auto_trace
Type: boolean, Default value: 0
When this setting is set to on, the tracing of function calls will be enabled just before the script is run. This makes it possible to trace code in the auto_prepend_file.

xdebug.collect_assignments
Type: boolean, Default value: 0, Introduced in Xdebug > 2.1
This setting, defaulting to 0, controls whether Xdebug should add variable assignments to function traces.

xdebug.collect_includes
Type: boolean, Default value: 1
This setting, defaulting to 1, controls whether Xdebug should write the filename used in include(), include_once(), require() or require_once() to the trace files.

xdebug.collect_params
Type: integer, Default value: 0

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.

ValueArgument Information Shown
0None.
1Type 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.

3Full 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.
4Full variable contents and variable name.
5PHP 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.


xdebug.collect_return
Type: boolean, Default value: 0

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.


xdebug.show_mem_delta
Type: integer, Default value: 0
When this setting is set to something != 0 Xdebug's human-readable generated trace files will show the difference in memory usage between function calls. If Xdebug is configured to generate computer-readable trace files then they will always show this information.

xdebug.trace_enable_trigger
Type: boolean, Default value: 0, Introduced in Xdebug > 2.2
When this setting is set to 1, you can trigger the generation of trace files by using the XDEBUG_TRACE GET/POST parameter, or set a cookie with the name XDEBUG_TRACE. This will then write the trace data to defined directory. In order to prevent Xdebug to generate trace files for each request, you need to set xdebug.auto_trace to 0.

xdebug.trace_format
Type: integer, Default value: 0

The format of the trace file.

ValueDescription
0shows 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.
1writes 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.
2writes a trace formatted in (simple) HTML.

Fields for the computerized format:

Record type123456789101112 - ...
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.


xdebug.trace_options
Type: integer, Default value: 0
When set to '1' the trace files will be appended to, instead of being overwritten in subsequent requests.

xdebug.trace_output_dir
Type: string, Default value: /tmp
The directory where the tracing files will be written to, make sure that the user who the PHP will be running as has write permissions to that directory.

xdebug.trace_output_name
Type: string, Default value: trace.%c

This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name. The '.xt' extension is always added automatically.

The possible format specifiers are:

SpecifierMeaningExample FormatExample Filename
%ccrc32 of the current working directorytrace.%ctrace.1258863198.xt
%ppidtrace.%ptrace.5174.xt
%rrandom numbertrace.%rtrace.072db0.xt
%s

script name 2

cachegrind.out.%scachegrind.out._home_httpd_html_test_xdebug_test_php
%ttimestamp (seconds)trace.%ttrace.1179434742.xt
%utimestamp (microseconds)trace.%utrace.1179434749_642382.xt
%H$_SERVER['HTTP_HOST']trace.%Htrace.kossu.xt
%R$_SERVER['REQUEST_URI']trace.%Rtrace._test_xdebug_test_php_var=1_var2=2.xt
%U$_SERVER['UNIQUE_ID'] 3trace.%Utrace.TRX4n38AAAEAAB9gBFkAAAAB.xt
%Ssession_id (from $_COOKIE if set)trace.%Strace.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


xdebug.var_display_max_children
Type: integer, Default value: 128

Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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.


xdebug.var_display_max_data
Type: integer, Default value: 512

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.


xdebug.var_display_max_depth
Type: integer, Default value: 3

Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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


string xdebug_get_tracefile_name()
Returns the name of the function trace file

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.


void xdebug_start_trace( string trace_file [, integer options] )
Starts a new function trace

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).
Unlike Xdebug 1, Xdebug 2 will not store function calls in memory, but always only write to disk to relieve the pressure on used memory. The settings xdebug.collect_includes, xdebug.collect_params and xdebug.collect_return influence what information is logged to the trace file and the setting xdebug.trace_format influences the format of the trace file.


void xdebug_stop_trace()
Stops the current function trace

Stop tracing function calls and closes the trace file.


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/Windows, 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 you can get precompiled binaries of KCacheGrind at SourceForge.

Users of Windows can also 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. 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


xdebug.profiler_append
Type: integer, Default value: 0
When this setting is set to 1, profiler files will not be overwritten when a new request would map to the same file (depnding on the xdebug.profiler_output_name setting. Instead the file will be appended to with the new profile.

xdebug.profiler_enable
Type: integer, Default value: 0
Enables Xdebug's profiler which creates files in the profile output directory. Those files can be read by KCacheGrind to visualize your data. This setting can not be set in your script with ini_set(). If you want to selectively enable the profiler, please set xdebug.profiler_enable_trigger to 1 instead of using this setting.

xdebug.profiler_enable_trigger
Type: integer, Default value: 0
When this setting is set to 1, you can trigger the generation of profiler files by using the XDEBUG_PROFILE GET/POST parameter, or set a cookie with the name XDEBUG_PROFILE. This will then write the profiler data to defined directory. In order to prevent the profiler to generate profile files for each request, you need to set xdebug.profiler_enable to 0.

xdebug.profiler_output_dir
Type: string, Default value: /tmp
The directory where the profiler output will be written to, make sure that the user who the PHP will be running as has write permissions to that directory. This setting can not be set in your script with ini_set().

xdebug.profiler_output_name
Type: string, Default value: cachegrind.out.%p

This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name.

See the xdebug.trace_output_name documentation for the supported specifiers.


Related Functions


string xdebug_get_profiler_filename()
Returns the profile information filename

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. There are two different protocols to communicate with the debugger: the old GDB-like command protocol (GDB) which is implemented in Xdebug 1.3 and 2; and the DBGp protocol which is implemented in Xdebug 2.

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:

A simple command line client for the GDB protocol is bundled with Xdebug 1.3. A client implementation of the deprecated GDB protocol can also be found in the free editor WeaverSlave.

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. 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:

  1. 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.
  2. If you want to debug a script started through a web browser, simply add XDEBUG_SESSION_START=session_name as parameter to the URL. Refer to the next section to read on how debug sessions work from within a browser window.
  3. Another way to activate the debugger while running PHP through a web server is by installing one of the following three browser extensions. Each of them allows you to simply enable the debugger by clicking on one button. 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". If you want to use the GDB commandset to debug your scripts, make sure you use a debugclient as bundled with Xdebug 1.3 as the one bundled with Xdebug 2 only works with the DBGp commandset.

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=name is appended to an URL 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.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.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.


Related Settings


xdebug.extended_info
Type: integer, Default value: 1
Controls whether Xdebug should enforce 'extended_info' mode for the PHP parser; this allows Xdebug to do file/line breakpoints with the remote debugger. When tracing or profiling scripts you generally want to turn off this option as PHP's generated oparrays will increase with about a third of the size slowing down your scripts. This setting can not be set in your scripts with ini_set(), but only in php.ini.

xdebug.idekey
Type: string, Default value: *complex*
Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last USERNAME. The default is set to the first environment variable that is found. If none could be found the setting has as default ''. If this setting is set, it always overrides the environment variables.

xdebug.remote_autostart
Type: boolean, Default value: 0
Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see Remote Debugging). When this setting is set to 1, Xdebug will always attempt to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE variable was not present.

xdebug.remote_connect_back
Type: boolean, Default value: 0, Introduced in Xdebug > 2.1
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['REMOTE_ADDR'] variable to find out which IP address to use. 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.

xdebug.remote_cookie_expire_time
Type: integer, Default value: 3600, Introduced in Xdebug > 2.1
This setting can be used to increase (or decrease) the time that the remote debugging session stays alive via the session cookie.

xdebug.remote_enable
Type: boolean, Default value: 0
This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.

xdebug.remote_handler
Type: string, Default value: dbgp

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.


xdebug.remote_host
Type: string, Default value: localhost
Selects the host where the debug client is running, you can either use a host name or an IP address. This setting is ignored if xdebug.remote_connect_back is enabled.

xdebug.remote_log
Type: string, Default value:
If set to a value, it is used as filename to a file to which all remote debugger communications are logged. The file is always opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available. The format of the file looks something like:
Log opened at 2007-05-27 14:28:15
-> <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>

xdebug.remote_mode
Type: string, Default value: req

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.

xdebug.remote_port
Type: integer, Default value: 9000
The port to which Xdebug tries to connect on the remote host. Port 9000 is the default for both the client and the bundled debugclient. As many clients use this port number, it is best to leave this setting unchanged.

Related Functions


bool xdebug_break()
Emits a breakpoint to the debug client.

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


xdebug.coverage_enable
Type: boolean, Default value: 1, Introduced in Xdebug >= 2.2
If this setting is set to 0, then Xdebug will not set-up internal structures to allow code coverage. This speeds up Xdebug quite a bit, but of course, Code Coverage Analysis won't work.

Related Functions


boolean xdebug_code_coverage_started()
Returns whether code coverage is active.

Returns whether code coverage has been started.

Example:

<?php
    var_dump
(xdebug_code_coverage_started());

    
xdebug_start_code_coverage();

    
var_dump(xdebug_code_coverage_started());
?>  

Returns:

bool(false)
bool(true)


array xdebug_get_code_coverage()
Returns code coverage information

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:

Example:

<?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());
?>  

Returns:

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

void xdebug_start_code_coverage( [int options] )
Starts code coverage

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
Value -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 you 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.
Enabling those options make code coverage drastically slower.

You can use the options as shown in the following example.

Example:

<?php
xdebug_start_code_coverage
XDEBUG_CC_UNUSED XDEBUG_CC_DEAD_CODE );
?>

void xdebug_stop_code_coverage( [int cleanup=true] )
Stops code coverage

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.xdebug.remote_port.
A: If you are running with SELinux you should make sure it is not preventing connections; look for warnings about name_connect or 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 phpize tool.
A: Debian and Ubuntu users need to install the php5-dev package with apt.
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.so to load Xdebug. This is not correct. In order to fix this issue, please look for a line extension=xdebug.so in 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:
  1. /full/path/to/php/bin/phpize
  2. ./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


xdebug.auto_trace
Type: boolean, Default value: 0
When this setting is set to on, the tracing of function calls will be enabled just before the script is run. This makes it possible to trace code in the auto_prepend_file.

xdebug.cli_color
Type: integer, Default value: 0, Introduced in Xdebug > 2.2

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.


xdebug.collect_assignments
Type: boolean, Default value: 0, Introduced in Xdebug > 2.1
This setting, defaulting to 0, controls whether Xdebug should add variable assignments to function traces.

xdebug.collect_includes
Type: boolean, Default value: 1
This setting, defaulting to 1, controls whether Xdebug should write the filename used in include(), include_once(), require() or require_once() to the trace files.

xdebug.collect_params
Type: integer, Default value: 0

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.

ValueArgument Information Shown
0None.
1Type 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.

3Full 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.
4Full variable contents and variable name.
5PHP 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.


xdebug.collect_return
Type: boolean, Default value: 0

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.


xdebug.collect_vars
Type: boolean, Default value: 0
This setting tells Xdebug to gather information about which variables are used in a certain scope. This analysis can be quite slow as Xdebug has to reverse engineer PHP's opcode arrays. This setting will not record which values the different variables have, for that use xdebug.collect_params. This setting needs to be enabled only if you wish to use xdebug_get_declared_vars().

xdebug.coverage_enable
Type: boolean, Default value: 1, Introduced in Xdebug >= 2.2
If this setting is set to 0, then Xdebug will not set-up internal structures to allow code coverage. This speeds up Xdebug quite a bit, but of course, Code Coverage Analysis won't work.

xdebug.default_enable
Type: boolean, Default value: 1
If this setting is 1, then stacktraces will be shown by default on an error event. You can disable showing stacktraces from your code with xdebug_disable(). As this is one of the basic functions of Xdebug, it is advisable to leave this setting set to 1.

xdebug.dump.*
Type: string, Default value: Empty

* can be any of COOKIE, FILES, GET, POST, REQUEST, SERVER, SESSION. These seven settings control which data from the superglobals is shown when an error situation occurs.

Each of those php.ini setting can consist of a comma 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 = *

xdebug.dump_globals
Type: boolean, Default value: 1
Controls whether the values of the superglobals as defined by the xdebug.dump.* settings should be shown or not.

xdebug.dump_once
Type: boolean, Default value: 1
Controls whether the values of the superglobals should be dumped on all error situations (set to 0) or only on the first (set to 1).

xdebug.dump_undefined
Type: boolean, Default value: 0
If you want to dump undefined values from the superglobals you should set this setting to 1, otherwise leave it set to 0.

xdebug.extended_info
Type: integer, Default value: 1
Controls whether Xdebug should enforce 'extended_info' mode for the PHP parser; this allows Xdebug to do file/line breakpoints with the remote debugger. When tracing or profiling scripts you generally want to turn off this option as PHP's generated oparrays will increase with about a third of the size slowing down your scripts. This setting can not be set in your scripts with ini_set(), but only in php.ini.

xdebug.file_link_format
Type: string, Default value: , Introduced in Xdebug > 2.1

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:

SpecifierMeaning
%fthe filename
%lthe 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"
  • 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 or gvim):
    • komodo $f -l $l
    • gvim --remote-tab +$l $f
  • 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.bat and save it in your path (C:\Windows will 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.bat batch file if you saved it somewhere else than C:\Windows\.

  • Double click on the netbeans_protocol.reg file to import it into the registry.
  • Set the xdebug.file_link_format setting to xdebug.file_link_format = "netbeans://open/?f=%f:%l"

xdebug.force_display_errors
Type: int, Default value: 0, Introduced in Xdebug 2.3

If this setting is set to 1 then errors will always be displayed, no matter what the setting of PHP's display_errors is.


xdebug.force_error_reporting
Type: int, Default value: 0, Introduced in Xdebug 2.3

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().


xdebug.halt_level
Type: int, Default value: 0, Introduced in Xdebug 2.3

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);
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.


xdebug.idekey
Type: string, Default value: *complex*
Controls which IDE Key Xdebug should pass on to the DBGp debugger handler. The default is based on environment settings. First the environment setting DBGP_IDEKEY is consulted, then USER and as last USERNAME. The default is set to the first environment variable that is found. If none could be found the setting has as default ''. If this setting is set, it always overrides the environment variables.

xdebug.manual_url
Type: string, Default value: http://www.php.net, Introduced in Xdebug < 2.2.1
This is the base url for the links from the function traces and error message to the manual pages of the function from the message. It is advisable to set this setting to use the closest mirror.

xdebug.max_nesting_level
Type: integer, Default value: 100
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.

xdebug.overload_var_dump
Type: boolean, Default value: 1, Introduced in Xdebug > 2.1

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. 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)


xdebug.profiler_append
Type: integer, Default value: 0
When this setting is set to 1, profiler files will not be overwritten when a new request would map to the same file (depnding on the xdebug.profiler_output_name setting. Instead the file will be appended to with the new profile.

xdebug.profiler_enable
Type: integer, Default value: 0
Enables Xdebug's profiler which creates files in the profile output directory. Those files can be read by KCacheGrind to visualize your data. This setting can not be set in your script with ini_set(). If you want to selectively enable the profiler, please set xdebug.profiler_enable_trigger to 1 instead of using this setting.

xdebug.profiler_enable_trigger
Type: integer, Default value: 0
When this setting is set to 1, you can trigger the generation of profiler files by using the XDEBUG_PROFILE GET/POST parameter, or set a cookie with the name XDEBUG_PROFILE. This will then write the profiler data to defined directory. In order to prevent the profiler to generate profile files for each request, you need to set xdebug.profiler_enable to 0.

xdebug.profiler_output_dir
Type: string, Default value: /tmp
The directory where the profiler output will be written to, make sure that the user who the PHP will be running as has write permissions to that directory. This setting can not be set in your script with ini_set().

xdebug.profiler_output_name
Type: string, Default value: cachegrind.out.%p

This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name.

See the xdebug.trace_output_name documentation for the supported specifiers.


xdebug.remote_autostart
Type: boolean, Default value: 0
Normally you need to use a specific HTTP GET/POST variable to start remote debugging (see Remote Debugging). When this setting is set to 1, Xdebug will always attempt to start a remote debugging session and try to connect to a client, even if the GET/POST/COOKIE variable was not present.

xdebug.remote_connect_back
Type: boolean, Default value: 0, Introduced in Xdebug > 2.1
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['REMOTE_ADDR'] variable to find out which IP address to use. 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.

xdebug.remote_cookie_expire_time
Type: integer, Default value: 3600, Introduced in Xdebug > 2.1
This setting can be used to increase (or decrease) the time that the remote debugging session stays alive via the session cookie.

xdebug.remote_enable
Type: boolean, Default value: 0
This switch controls whether Xdebug should try to contact a debug client which is listening on the host and port as set with the settings xdebug.remote_host and xdebug.remote_port. If a connection can not be established the script will just continue as if this setting was 0.

xdebug.remote_handler
Type: string, Default value: dbgp

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.


xdebug.remote_host
Type: string, Default value: localhost
Selects the host where the debug client is running, you can either use a host name or an IP address. This setting is ignored if xdebug.remote_connect_back is enabled.

xdebug.remote_log
Type: string, Default value:
If set to a value, it is used as filename to a file to which all remote debugger communications are logged. The file is always opened in append-mode, and will therefore not be overwritten by default. There is no concurrency protection available. The format of the file looks something like:
Log opened at 2007-05-27 14:28:15
-> <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>

xdebug.remote_mode
Type: string, Default value: req

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.

xdebug.remote_port
Type: integer, Default value: 9000
The port to which Xdebug tries to connect on the remote host. Port 9000 is the default for both the client and the bundled debugclient. As many clients use this port number, it is best to leave this setting unchanged.

xdebug.scream
Type: boolean, Default value: 0, Introduced in Xdebug >= 2.1
If this setting is 1, then Xdebug will disable the @ (shut-up) operator so that notices, warnings and errors are no longer hidden.

xdebug.show_exception_trace
Type: integer, Default value: 0
When this setting is set to 1, Xdebug will show a stack trace whenever an exception is raised - even if this exception is actually caught.

xdebug.show_local_vars
Type: integer, Default value: 0
When this setting is set to something != 0 Xdebug's generated stack dumps in error situations will also show all variables in the top-most scope. Beware that this might generate a lot of information, and is therefore turned off by default.

xdebug.show_mem_delta
Type: integer, Default value: 0
When this setting is set to something != 0 Xdebug's human-readable generated trace files will show the difference in memory usage between function calls. If Xdebug is configured to generate computer-readable trace files then they will always show this information.

xdebug.trace_enable_trigger
Type: boolean, Default value: 0, Introduced in Xdebug > 2.2
When this setting is set to 1, you can trigger the generation of trace files by using the XDEBUG_TRACE GET/POST parameter, or set a cookie with the name XDEBUG_TRACE. This will then write the trace data to defined directory. In order to prevent Xdebug to generate trace files for each request, you need to set xdebug.auto_trace to 0.

xdebug.trace_format
Type: integer, Default value: 0

The format of the trace file.

ValueDescription
0shows 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.
1writes 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.
2writes a trace formatted in (simple) HTML.

Fields for the computerized format:

Record type123456789101112 - ...
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.


xdebug.trace_options
Type: integer, Default value: 0
When set to '1' the trace files will be appended to, instead of being overwritten in subsequent requests.

xdebug.trace_output_dir
Type: string, Default value: /tmp
The directory where the tracing files will be written to, make sure that the user who the PHP will be running as has write permissions to that directory.

xdebug.trace_output_name
Type: string, Default value: trace.%c

This setting determines the name of the file that is used to dump traces into. The setting specifies the format with format specifiers, very similar to sprintf() and strftime(). There are several format specifiers that can be used to format the file name. The '.xt' extension is always added automatically.

The possible format specifiers are:

SpecifierMeaningExample FormatExample Filename
%ccrc32 of the current working directorytrace.%ctrace.1258863198.xt
%ppidtrace.%ptrace.5174.xt
%rrandom numbertrace.%rtrace.072db0.xt
%s

script name 2

cachegrind.out.%scachegrind.out._home_httpd_html_test_xdebug_test_php
%ttimestamp (seconds)trace.%ttrace.1179434742.xt
%utimestamp (microseconds)trace.%utrace.1179434749_642382.xt
%H$_SERVER['HTTP_HOST']trace.%Htrace.kossu.xt
%R$_SERVER['REQUEST_URI']trace.%Rtrace._test_xdebug_test_php_var=1_var2=2.xt
%U$_SERVER['UNIQUE_ID'] 3trace.%Utrace.TRX4n38AAAEAAB9gBFkAAAAB.xt
%Ssession_id (from $_COOKIE if set)trace.%Strace.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


xdebug.var_display_max_children
Type: integer, Default value: 128

Controls the amount of array children and object's properties are shown when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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.


xdebug.var_display_max_data
Type: integer, Default value: 512

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.


xdebug.var_display_max_depth
Type: integer, Default value: 3

Controls how many nested levels of array elements and object properties are when variables are displayed with either xdebug_var_dump(), xdebug.show_local_vars or 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


void var_dump( [mixed var [, ...]] )
Displays detailed information about a variable

This function is overloaded by Xdebug, see the description for xdebug_var_dump().


bool xdebug_break()
Emits a breakpoint to the debug client.

This function makes the debugger break on the specific line as if a normal file/line breakpoint was set on this line.


string xdebug_call_class()
Returns the calling class

This function returns the name of the class from which the current function/method was called from.

Example:

<?php
    
function fix_string($a)
    {
        echo 
"Called @ ".
            
xdebug_call_file().
            
":".
            
xdebug_call_line().
            
" from ".
            
xdebug_call_function();
    }

    
$ret fix_string(array('Derick'));
?>

Returns:

Called @ /home/httpd/html/test/xdebug_caller.php:12 from {main}

string xdebug_call_file()
Returns the calling file

This function returns the filename that contains the function/method that called the current function/method.

For an example see xdebug_call_class().


string xdebug_call_function()
Returns the calling function/method

This function returns the name of the function/method from which the current function/method was called from.

For an example see xdebug_call_class().


int xdebug_call_line()
Returns the calling line

This function returns the line number that contains the function/method that called the current function/method.

For an example see xdebug_call_class().


boolean xdebug_code_coverage_started()
Returns whether code coverage is active.

Returns whether code coverage has been started.

Example:

<?php
    var_dump
(xdebug_code_coverage_started());

    
xdebug_start_code_coverage();

    
var_dump(xdebug_code_coverage_started());
?>  

Returns:

bool(false)
bool(true)


void xdebug_debug_zval( [string varname [, ...]] )
Displays information about a variable

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.

Example:

<?php
    $a 
= array(123);
    
$b =& $a;
    
$c =& $a[2];

    
xdebug_debug_zval('a');
    
xdebug_debug_zval("a[2]");
?>

Returns:

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

void xdebug_debug_zval_stdout( [string varname [, ...]] )
Returns information about variables to stdout.

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).

Example:

<?php
    $a 
= array(123);
    
$b =& $a;
    
$c =& $a[2];

    
xdebug_debug_zval_stdout('a');

Returns:

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)

void xdebug_disable()
Disables stack traces

Disable showing stack traces on error conditions.


void xdebug_dump_superglobals()
Displays information about super globals

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:

Example:

xdebug.dump.GET=*
xdebug.dump.SERVER=REMOTE_ADDR

Query string:
?var=fourty%20two&array[a]=a&array[9]=b

Returns:

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)

void xdebug_enable()
Enables stack traces

Enable showing stack traces on error conditions.


array xdebug_get_code_coverage()
Returns code coverage information

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:

Example:

<?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());
?>  

Returns:

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

void xdebug_get_collected_errors( [int clean] )
Returns all collected error messages
Introduced in version 2.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 true as argument to this function then the buffer will be cleared as well.

This function returns a string containing all collected errors formatted as an "Xdebug table".


array xdebug_get_declared_vars()
Returns declared variables

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.

Example:

<?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));
?>

Returns:

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.


array xdebug_get_function_stack()
Returns information about the stack

Returns an array which resembles the stack trace up to this point. The example script:

Example:

<?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'));
?>

Returns:

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)


array xdebug_get_headers()
Returns all the headers as set by calls to PHP's header() function
Introduced in version 2.1

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.

Example:

<?php
header
"X-Test""Testing" );
setcookie"TestCookie""test-value" );
var_dumpxdebug_get_headers() );
?>

Returns:

array(2) {
  [0]=>
  string(6) "X-Test"
  [1]=>
  string(33) "Set-Cookie: TestCookie=test-value"
}

string xdebug_get_profiler_filename()
Returns the profile information filename

Returns the name of the file which is used to save profile information to.


integer xdebug_get_stack_depth()
Returns the current stack depth level

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.


string xdebug_get_tracefile_name()
Returns the name of the function trace file

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.


bool xdebug_is_enabled()
Returns whether stack traces are enabled

Return whether stack traces would be shown in case of an error or not.


int xdebug_memory_usage()
Returns the current memory usage

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.


int xdebug_peak_memory_usage()
Returns the peak memory usage

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.


none xdebug_print_function_stack( [ string message [, int options ] ] )
Displays the current function stack.

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).

Example:

<?php
function foo$far$out )
{
    
xdebug_print_function_stack'Your own message' );
}
foo423141592654 );
?>

Returns:

( ! ) Xdebug: Your own message in /home/httpd/html/test/xdebug/print_function_stack.php on line 5
Call Stack
#TimeMemoryFunctionLocation
10.0006653896{main}( )../print_function_stack.php:0
20.0007654616foo( 42, 3141592654 )../print_function_stack.php:7
30.0007654736xdebug_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).


void xdebug_start_code_coverage( [int options] )
Starts code coverage

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
Value -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 you 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.
Enabling those options make code coverage drastically slower.

You can use the options as shown in the following example.

Example:

<?php
xdebug_start_code_coverage
XDEBUG_CC_UNUSED XDEBUG_CC_DEAD_CODE );
?>

void xdebug_start_error_collection()
Starts recording all notices, warnings and errors and prevents their display
Introduced in version 2.1

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.


void xdebug_start_trace( string trace_file [, integer options] )
Starts a new function trace

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).
Unlike Xdebug 1, Xdebug 2 will not store function calls in memory, but always only write to disk to relieve the pressure on used memory. The settings xdebug.collect_includes, xdebug.collect_params and xdebug.collect_return influence what information is logged to the trace file and the setting xdebug.trace_format influences the format of the trace file.


void xdebug_stop_code_coverage( [int cleanup=true] )
Stops code coverage

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.


void xdebug_stop_error_collection()
Stops recording of all notices, warnings and errors as started by xdebug_start_error_collection()
Introduced in version 2.1

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().


void xdebug_stop_trace()
Stops the current function trace

Stop tracing function calls and closes the trace file.


float xdebug_time_index()
Returns the current time index

Returns the current time index since the starting of the script in seconds.

Example:

<?php
echo xdebug_time_index(), "\n";
for (
$i 0$i 250000$i++)
{
    
// do nothing
}
echo 
xdebug_time_index(), "\n";
?>

Returns:

0.00038003921508789
0.76580691337585

void xdebug_var_dump( [mixed var [, ...]] )
Displays detailed information about a variable

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.

Example:

<?php
ini_set
('xdebug.var_display_max_children');
$c = new stdClass;
$c->foo 'bar';
$c->file fopen'/etc/passwd''r' );
var_dump(
    array(
        array(
TRUE23.14'foo'),
        
'object' => $c
    
)
);
?>  

Returns:

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)

 
 
This site and all of its contents are Copyright © 2002-2014 by Derick Rethans.
All rights reserved.