Xdebug能让你把所有函数调用,包括参数和返回值以不同的格式记录到文件中。
这些号称“函数跟踪”功能能帮助你面对一个新应用程序,亦或者在程序运行时你想弄清楚它在做什么。函数跟踪功能可以选择性地显示函数或方法传递的变量值,也可以是返回值。跟踪这两个元素默认情况下不开启的。
输出格式
共有三种输出格式。一种是人类可读性跟踪信息,另一个是更适合计算机程序解析的,最后一种使用HTML格式化跟踪信息的。你可以使用xdebug_trace_format设置切换这两种不周的格式。还有一些设置是控制哪些信息写入跟踪文件的。例如设置包含变量的(xdebug.collect_params)和包含返回值的(xdebug.collect_return)。以下例子展示人类可读性的函数跟踪信息的不同设置效果:
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
以下由xdebug.collect_params设置不同值时的结果。当不在web环境下,2值不包含鼠标提示。
默认值:
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]
Collect_params=1:
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]
Collect_params=3:
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]
Collect_params=4:
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]
除了xdebug.collet_params设置还有另一些设置影响跟踪文件的输出效果。“show_mem_delta=1”可以显示内存使用量在两个不同列中。
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]
“collect_return=1”显示被调用函数的返回值:
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]
“collect_assignments=1”显示变量赋予,详见xdebug.collect_assignments设置。
“xdebug.trace_format”设置改变输出格式让解析更容易但反而让人更难理解。这对于用第三方工具解析跟踪文件最有用处。
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 语法文件
Xdebug 携带一个VIM语法文件能对跟踪文件的语法提亮,该语法文件名:xt.vim。 为了使VIM识别新格式,你需这么做:
- 复制xt.vim文件到 ~/.vim/syntax
- 编辑或创建 ~/.vim/filetype.vim 文件,并添加以下代码:
augroup filetypedetect
au BufNewFile,BufRead *.xt setf xt
augroup END
做完这些后,打开的跟踪文件就会类似这样:
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]
相关设置:
xdebug.auto_trace
类型: boolean, 默认值: 0
打开此设置时,脚本在运行前函数调用追踪将开启。这将可能追踪auto_prepend_file设置的代码文件。
xdebug.collect_assignments
类型: boolean, 默认值: 0, 始于 Xdebug > 2.1
用于控制xdebug是否添加变量赋予到函数追踪当中。
xdebug.collect_includes
类型: boolean, 默认值: 1
用于控制xdebug是否将include(), include_once(), require() 或 require_once() 引用的文件名写入到跟踪文件中。
xdebug.collect_params
类型: integer, 默认值: 0
默认为0时,该设置控制xdebug不管是函数追踪还是堆栈跟踪都会收集调用函数的参数。
默认0值是考虑到大规模脚本会占用大量内存,所以不会为了大脚本来运行它。你可以安全地打开此设置,但你会预料到会一些脚本上的问题像大量函数调用兼庞大的数据结构作为参数传递。Xdebug2不会有增加内存使用的问题,因为它不会存储到内存,而是只存入磁盘中。这只需要你有足够的磁盘使用量即可。
该设置有4种设置值。每种都会呈现不同的信息。以下表格展示各种设置值信息:
Value |
Argument Information Shown |
0 |
无. |
1 |
展示变量元素的值类型和值。 |
2 |
展示变量元素的值类型和值,并附带滑鼠提示显示完整信息。(CLI模式下不存在滑鼠提示) |
3 |
完整变量内容(内容受限于以下设置: xdebug.var_display_max_children,xdebug.var_display_max_data and xdebug.var_display_max_depth.) |
4 |
完整变量内容和名称。 |
5 |
PHP 序列化变量内容,不含名称。(2.3版本新特性) |
xdebug.collect_return
类型: boolean, 默认值: 0
控制是否将函数调用的返回值写入到跟踪文件里。
要达到计算机化跟踪文件(xdebug.trace_format=1) 必须要用到Xdebug 2.3 以上版本。
xdebug.show_mem_delta
类型: integer, 默认值: 0
当此设置不为0值,可人为读取的跟踪文件将各函数调用占用内存量的不同。如果xdebug设置为产生计算机可读的跟踪文件,则他们会一直显示这样的信息。
xdebug.trace_enable_trigger
类型: boolean, 默认值: 0, 始于 Xdebug > 2.2
设置为1时,你能使用XDEBUG_TRACE GET/POST 参数或设置一名为XDEBUG_TRACE的cookie值触发跟踪文件的产生。跟踪数据文件将写入到预定义文件夹内。为了防止xdebug在每次请求时产生跟踪文件,你需要将xdebug.auto_trace设为0。访问触发器自身可通过设置 xdebug.trace_enable_trigger_value。
xdebug.trace_enable_trigger_value
类型: string, 默认值: "", 始于 Xdebug > 2.3
该设置用于限制谁能利用XDEBUG_TRACE功能描述到xdebug.trace_enable_trigger。当变更了默认空值后,cookie,GET或POST值需要为跟踪文件的产生匹配设置内的共享隐藏设置。
xdebug.trace_format
类型: integer, 默认值: 0
跟踪文件的格式。
值 |
描述 |
0 |
显示人类可读性排版式文件:时间点,内存量,内存增量(如果xdebug.show_mem_delta 开启), 层级, 函数名, 函数参数 (如果 xdebug.collect_params 开启),文件名和行号。 |
1 |
用两种不同记录编写记算机可读格式文件。其记录不同在于一个插入堆栈边框,一个移除堆栈边框。以下表格列出记录中每个栏位区别。 |
2 |
使用HTML写成跟踪文件。 |
计算机化格式的栏位:
Record type |
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 - ... |
Entry |
level |
function # |
always ‘0‘ |
time index |
memory usage |
function name |
user-defined (1) or internal function (0) |
name of the include/require file |
filename |
line number |
no. of parameters |
parameters (as many as specified in field 11) - tab separated |
Exit |
level |
function # |
always ‘1‘ |
time index |
memory usage |
empty |
||||||
Return |
level |
function # |
always ‘R‘ |
empty |
return value |
empty |
xdebug.trace_options
类型: integer, 默认值: 0
设为1时跟踪文件会后续添加内容,而不是在后续请求中直接覆盖。
xdebug.trace_output_dir
类型: string, 默认值: /tmp
跟踪文件写入路径,确保用户在运行PHP时有对该目录的写入权限。
xdebug.trace_output_name
类型: string, 默认值: trace.%c
该设置决定了跟踪信息写入的文件名。该设置使用了格式化标识符,类似于sprintf() 和 strftime()。 以几种格式标识符可以用于格式化文件名。后缀名 ‘.xt‘ 会自动地添加到文件名后。
格式化标识符列表:
标识符 |
意义 |
格式范例 |
文件范例 |
%c |
当前工作路径的crc32效验值 |
trace.%c |
trace.1258863198.xt |
%p |
进程标识符 |
trace.%p |
trace.5174.xt |
%r |
随机数 |
trace.%r |
trace.072db0.xt |
%s |
脚本名 2 |
cachegrind.out.%s |
cachegrind.out._home_httpd_html_test_xdebug_test_php |
%t |
时间截 (秒) |
trace.%t |
trace.1179434742.xt |
%u |
时间截 (微秒) |
trace.%u |
trace.1179434749_642382.xt |
%H |
$_SERVER[‘HTTP_HOST‘] |
trace.%H |
trace.kossu.xt |
%R |
$_SERVER[‘REQUEST_URI‘] |
trace.%R |
trace._test_xdebug_test_php_var=1_var2=2.xt |
%U |
$_SERVER[‘UNIQUE_ID‘] 3 |
trace.%U |
trace.TRX4n38AAAEAAB9gBFkAAAAB.xt |
%S |
session_id (来源$_COOKIE,如果有设置) |
trace.%S |
trace.c70c1ec2375af58f74b390bbdd2a679d.xt |
%% |
literal % |
trace.%% |
trace.%%.xt |
2 对于跟踪文件名这是不可用的。
3 版本2.2新特性。该特性由Apache mod_unique_id module 设置。
xdebug.var_display_max_children
类型: integer, 默认值: 128
在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制数组元素和对象属性的数量显示。
若不受限制,可以设为-1值。
该设置不受Remot_Debuggin远程调试的任何影响。
xdebug.var_display_max_data
类型: integer, 默认值: 512
在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制字符串长度显示最大值。
若不受限制,可以设为-1值。
该设置不受Remot_Debugging远程调试的任何影响。
xdebug.var_display_max_depth
类型: integer, 默认值: 3
在使用 xdebug_var_dump(),xdebug.show_local_vars 或 追踪函数时,该设置控制数组元素和对象属性的显示层级。
最大值为1023,你可以设为-1表示其最大值。
该设置不受Remot_Debugging远程调试的任何影响。
相关函数:
string xdebug_get_tracefile_name()
返回当前跟踪输出的脚本文件名。当xdebug.auto_trace打开时这个函数就能使用了。
void xdebug_start_trace( string trace_file [, integer options] )
启动一新的函数跟踪
位于某个点开始函数跟踪并入到参数trace_file指定的文件中。如果没有指定文件名,则跟踪文件存入 xdebug.trace_output_dir设定指定目录中。一旦在第一参数中指定了文件名,则该名称相对于当前工作目录。不过当前工作目录可能与你期望的不一样,所以在指定文件名时最好指定绝对目录。PHP函数 getcwd() 能指出当前工作目录。
跟踪文件名一般是"{trace_file}.xt"。如果 xdebug.auto_trace 开启,那么文件名"{filename}.xt"的"{filename}"部分由设置 xdebug.trace_output_name 决定。参数options是比特值,有三种选项:
XDEBUG_TRACE_APPEND (1)
使跟踪文件以追加模式打开而不是覆盖模式。
XDEBUG_TRACE_COMPUTERIZED (2)
创建一个跟踪文件而其格式由"xdebug.trace_format"描述。
XDEBUG_TRACE_HTML (4)
以html表格创建跟踪文件。
XDEBUG_TRACE_NAKED_FILENAME (8)
一般来说,Xdebug会添加".xt"到你指定的第一个参数的文件名结尾。使用XDEBUG_TRACE_NAKED_FILENAME选项, ".xt" 则不会再添加 (Xdebug 2.3新特性).
不像Xdebug 1,Xdebug 2不会在函数调用时占用内存。,但它会写入磁盘而缓解内存使用的压力。 xdebug.collect_includes, xdebug.collect_params 和xdebug.collect_return 等设置会影响跟踪文件记录什么样的信息,而xdebug.trace_format 则影响文件信息的格式。
void xdebug_stop_trace()
停止跟踪函数调用并关闭跟踪文件。