Xdebug: Documentation

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

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.

Example:


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

    xdebug_debug_zval('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_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(1, 2, 3);
    $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_dump( xdebug_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 ] )

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 was introduced in Xdebug 2.1.

Example:


<?php
function foo( $far, $out )
{
    xdebug_print_function_stack( 'Your own message' );
}
foo( 42, 3141592654 );
?>

Returns:


( ! ) Xdebug: Your own message in /home/httpd/html/test/xdebug/print_function_stack.php on line 5
Call Stack
# Time Memory Function Location
1 0.0006 653896 {main}(  ) ../print_function_stack.php:0
2 0.0007 654616 foo( 42, 3141592654 ) ../print_function_stack.php:7
3 0.0007 654736 xdebug_print_function_stack
( 'Your own message' ) ../print_function_stack.php:5

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 the total number of execution units on this line have been executed.

Options to this function are: XDEBUG_CC_UNUSED Enables scanning of code to figure out which line has executable code. XDEBUG_CC_DEAD_CODE Enables branch analyzes to figure out whether code can be executed.

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

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', 3 );
$c = new stdClass;
$c->foo = 'bar';
$c->file = fopen( '/etc/passwd', 'r' );
var_dump(
    array(
        array(TRUE, 2, 3.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)

Related Functions