Xdebug  
  XDEBUG EXTENSION FOR PHP | DOCUMENTATION - FUNCTION REFERENCE
home | updates | installation | documentation | screenshots | license | support



INTRODUCTION

This page lists all available functions in Xdebug. First a short description of each function per section is shown, with links to the full description of a functions, and in some cases examples.

Functions marked with [1] in the following index are only available in Xdebug 1.3 and all functions marked with [2] are only available in Xdebug 2.x. All unmarked functions are available in both Xdebug 1.3 and Xdebug 2.x.

ACTIVATION RELATED FUNCTIONS
xdebug_disable()
disables displaying stacktraces on errors
xdebug_enable()
enables displaying stacktraces on errors
xdebug_is_enabled()
returns whether stacktraces would be shown in case of errors
CODE COVERAGE FUNCTIONS
xdebug_get_code_coverage()
returns an array containing information on which lines are touched while executing the script
xdebug_get_function_count() [2]
returns the number of functions called since the beginning of the script
xdebug_start_code_coverage()
starts collecting information on which lines are touched while executing the script
xdebug_stop_code_coverage()
stops collecting information on which lines are touched while executing the script
EXECUTION RELATED FUNCTIONS
xdebug_dump_function_trace() [1]
displays all functions called since xdebug_start_trace() as an HTML table
xdebug_get_function_trace() [1]
returns all functions called since xdebug_start_trace() as an array
xdebug_memory_usage()
returns the current amount of script memory in use
xdebug_peak_memory_usage() [2]
returns the maximum amount of memory used at one point
xdebug_start_trace()
starts tracing all function calls to a file
xdebug_stop_trace()
stops tracing all function calls to a file
xdebug_time_index()
returns the time since the start of the script
INFORMATION DUMPING RELATED FUNCTIONS
xdebug_dump_superglobals()
dumps values of elements of superglobals
xdebug_var_dump()
displays an HTML colourized representation of one or more variables
PROFILING RELATED FUNCTIONS
xdebug_dump_function_profile() [1]
displays two tables with profiling information
xdebug_get_function_profile() [1]
return the profiling profile nformation on which lines are touched while executing the script
xdebug_start_profiling() [1]
returns an array containing information on which lines are touched while executing the script
xdebug_stop_profiling() [1]
returns an array containing information on which lines are touched while executing the script
REMOTE DEBUGGING RELATED FUNCTIONS
xdebug_break() [2]
makes the remote debugger break as if a breakpoint was set on this line
STACK RELATED FUNCTIONS
xdebug_call_class()
returns the class from which the current function was called
xdebug_call_file()
returns the file name from which the current function was called
xdebug_call_function()
returns the function from which the current function was called
xdebug_call_line()
returns the line number from which the current function was called
xdebug_get_function_stack()
returns an array representing the current stack
xdebug_get_stack_depth() [2]
returns the stack depth


STACK RELATED
array xdebug_get_function_stack()
Returns an array which resembles the stack trace up to this point. The example script:

 1 <?php
2     
class strings {
3         function fix_string($a)
4         {
5             var_dump (xdebug_get_function_stack());
6         }
7
8         
function fix_strings($b) {
9             foreach ($b as $item) {
10                 $this->fix_string($item);
11             }
12         }
13     }
14
15     $s
= new strings();
16     $ret = $s->fix_strings(array('Derick'));
17 ?>
Returns:
array(3) {
  [0]=>
  array(4) {
    ["function"]=>
    string(6) "{main}"
    ["file"]=>
    string(38) "/home/httpd/html/test/xdebug_error.html"
    ["line"]=>
    int(0)
    ["params"]=>
    array(0) {
    }
  }
  [1]=>
  array(5) {
    ["function"]=>
    string(11) "fix_strings"
    ["class"]=>
    string(7) "strings"
    ["file"]=>
    string(38) "/home/httpd/html/test/xdebug_error.html"
    ["line"]=>
    int(16)
    ["params"]=>
    array(1) {
      [0]=>
      string(21) "array (0 => 'Derick')"
    }
  }
  [2]=>
  array(5) {
    ["function"]=>
    string(10) "fix_string"
    ["class"]=>
    string(7) "strings"
    ["file"]=>
    string(38) "/home/httpd/html/test/xdebug_error.html"
    ["line"]=>
    int(10)
    ["params"]=>
    array(1) {
      [0]=>
      string(8) "'Derick'"
    }
  }
}
integer xdebug_get_stack_depth() (Xdebug 2)
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_call_class()
string xdebug_call_function()
string xdebug_call_file()
int xdebug_call_line()
These four functions return information about the function that called the current one, or FALSE when there was no previous function. This example script:

 1 <?php
2     
function fix_string($a)
3     {
4         echo "Called @ ".
5             xdebug_call_file().
6             ":".
7             xdebug_call_line().
8             " from ".
9             xdebug_call_function();
10     }
11
12     $ret
= fix_string(array('Derick'));
13 ?>
prints:
Called @ /home/httpd/html/test/xdebug_caller.html:12 from {main}

ACTIVATION RELATED
void xdebug_enable()
Enable showing stacktraces on error conditions.
void xdebug_disable()
Disable showing stacktraces on error conditions.
bool xdebug_is_enabled()
Return whether stacktraces would be shown in case of an error or not.

TRACING AND EXECUTING RELATED
void xdebug_start_trace([string trace_file]) (Xdebug 1)
Start tracing function calls from this point. If the trace_file parameter is specified the function calls will also be logged to this file. Please note that all function calls are stored in memory here; with large scripts this will definitely exhaust memory on your machine. In order for this functionality to be useful it is strongly recommended to turn off the xdebug.collect_params setting.
void xdebug_start_trace(string trace_file [, integer options]) (Xdebug 2)
Start tracing function calls from this point to the file in the trace_file parameter. The trace file will be placed in the directory as configured by the trace_output_dir setting. The name of the trace file is "xdebug.{hash}.xt" where the "{hash}" part depends on the trace_output_name setting. The options parameter is a bitfield; currently there are two options: "XDEBUG_TRACE_APPEND" (1) makes the trace file open in append mode rather than overwrite mode and "XDEBUG_TRACE_COMPUTERIZED" (2) creates a trace file with the format as described under 1 here. 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 collect_includes, collect_params and collect_return influence what information is logged to the trace file and the setting trace_format influences the format of the trace file.
void xdebug_stop_trace() (Xdebug 1)
Stop tracing function calls and destroys the trace currently in memory.
void xdebug_stop_trace() (Xdebug 2)
Stop tracing function calls and closes the tracefile.
array xdebug_get_function_trace() (Xdebug 1)
Returns all function calls since xdebug_start_trace(). For the following script:

 1 <?php
2     xdebug_start_trace
();
3     function fix_string($a)
4     {
5         echo "Called @ ".
6             xdebug_call_file().
7             ":".
8             xdebug_call_line().
9             " from ".
10             xdebug_call_function();
11     }
12
13     $ret
= fix_string(array('Derick'));
14     var_dump(xdebug_get_function_trace());
15 ?>
returns an array in which each element represents one function call (much like the stack trace) above. Each element contains the following information:
  array(6) {
    ["function"]=>
    string(10) "fix_string"
    ["file"]=>
    string(39) "/home/httpd/html/test/xdebug_caller.html"
    ["line"]=>
    int(13)
    ["time_index"]=>
    float(0)
    ["memory_usage"]=>
    int(37720)
    ["params"]=>
    array(1) {
      [1]=>
      string(21) "array (0 => 'Derick')"
    }
  }
void xdebug_dump_function_trace() (Xdebug 1)
If you don't want to return the information in an array, but simply want to display the trace information you can use this function. If we modify line 14 of the example above to say

 1 <?php
14     xdebug_dump_function_trace
();
15 ?>
the following table with information is shown:
Function trace
Time#FunctionLocationMemory
0
  ->
fix_string(array (0 => 'Derick'))/home/httpd/html/test/xdebug_caller.html:1337352
0.000096
    ->
xdebug_call_file ()/home/httpd/html/test/xdebug_caller.html:637408
0.000117
    ->
xdebug_call_line ()/home/httpd/html/test/xdebug_caller.html:837464
0.000137
    ->
xdebug_call_function ()/home/httpd/html/test/xdebug_caller.html:1037472
int xdebug_memory_usage()
Returns the current amount of memory the script uses. (Only works when PHP was compiled with --enable-memory-limit).
int xdebug_peak_memory_usage() (Xdebug 2)
Returns the maximum amount of memory the script used up til now. (Only works when PHP was compiled with --enable-memory-limit).
float xdebug_time_index()
Returns the current time index since the starting of the script in seconds.


CODE COVERAGE RELATED
void xdebug_start_code_coverage()
This function starts gathering the information for code coverage. The information that is collected constists of an two dimensional array with as primairy index the executed filename and as secondairy key the line number. The value in the elements represents the total number of execution units on this line have been executed.
void xdebug_stop_code_coverage()
This function stops collecting information, the information in memory will not be destroyed so that you can resume the gathering of information with the xdebug_start_code_coverage() function again.
array xdebug_get_code_coverage()
Returns a structure which contains information about how many times an execution units were executed on the specified line in your script (including include files). The following example:

 1 <?php
2     xdebug_start_code_coverage
();
3
4     
function a($a) {
5         echo $a * 2.5;
6     }
7
8     
function b($count) {
9         for ($i = 0; $i < $count; $i++) {
10             a($i + 0.17);
11         }
12     }
13
14     b
(6);
15     b(10);
16
17     var_dump
(xdebug_get_code_coverage());
18 ?>  
returns this array:
array(1) {
  ["/home/httpd/html/test/xdebug_coverage.html"]=>
  array(10) {
    [4]=>
    int(1)
    [5]=>
    int(16)
    [6]=>
    int(16)
    [8]=>
    int(1)
    [9]=>
    int(20)
    [10]=>
    int(16)
    [12]=>
    int(2)
    [14]=>
    int(1)
    [15]=>
    int(1)
    [17]=>
    int(1)
  }
}
int xdebug_get_function_count()
This function returns the number of functions called since the beginning of the script, including the call to xdebug_get_function_count() itself.

PROFILING RELATED
void xdebug_start_profiling() (Xdebug 1)
void xdebug_stop_profiling() (Xdebug 1)
void xdebug_dump_function_profile([int profiling_mode]) (Xdebug 1)
array xdebug_get_function_profile([int profiling_mode]) (Xdebug 1)
Please see the section on Profiling (Xdebug 1) for information about these functions or Profiling (Xdebug 2).

INFORMATION DUMPING RELATED
void xdebug_dump_superglobals()
This function dumps the values of the elements of the superglobals as specifed with the 'xdebug.dump.' php.ini settings as decribed in the section settings. An example output might look like (the only ini setting that is made for this is 'xdebug.dump.SERVER = REMOTE_ADDR'):
Dump $_SERVER
$_SERVER['REMOTE_ADDR']'127.0.0.1'
void xdebug_var_dump([mixed var [, ...]])
This function displays structured information about one or more expressions that includes its type and value. Arrays are explored recursively with values

 1 <?php
2     var_dump
(
3         array(
4             array(TRUE, FALSE, 3),
5             'twee' => array('4', NULL, '6')
6         )
7     );
8 ?>  
displays:


REMOTE DEBUGGING RELATED
bool xdebug_break() (Xdebug 2)
This function makes the debugger break on the specific line as if a normal file/line breakpoint was set on this line.


 
RELEASES
[29-11-2004]
Source:
Debug client 0.8.0 (binary):
[15-09-2004]
Windows modules:
[30-06-2004]
Source:
Modules for 4.3.x (binary):
Debug client 0.7.0 (binary):

DEVELOPMENT VERSION (2.0dev)
Instructions to get Xdebug 2.0dev from CVS can be found here. This version compiles on PHP 4.3.0 and higher.

BINARY SNAPSHOTS (2.0dev)
Modules for 4.3.x-dev:
Modules for 5.0.x-dev:
Modules for 5.1.x-dev:

OLDER RELEASES
Source:

 
 
This site and all of its contents are Copyright © 2002, 2003, 2004 by Derick Rethans.
All rights reserved.