PHP XDEBUG 扩展 | 文档

Xdebug 允许记录所有的函数调用，记录文件中包含不同格式的参数和返回值。

这里之所以叫 "函数跟踪" 是当你新建一个应用或尝试了解应用运行时具体是怎样进行的会有所帮助。函数跟踪可以选择性的显示传递到函数和方法的变量值以及返回值。默认跟踪中这两个元素是不可见的。

输出格式

这里有三种输出格式。一种是供人类阅读的跟踪信息，另一种是更适用于计算机程序让其更容易解析，最后一种是使用 HTML 格式的跟踪信息。你可以使用设置 xdebug.trace_format 在两种不同的格式之间切换。这里的一些设置能控制哪些信息能被写入跟踪文件。示例中的设置包括变量 xdebug.collect_params 和 xdebug.collect_return 返回值。下面的示例展示了不同设置在供人类可读的函数跟踪中的影响。

脚本

<?php
$str = "Xdebug";
function ret_ord( $c )
{
    return ord( $c );
}

foreach ( str_split( $str ) as $char )
{
    echo $char, ": ", ret_ord( $char ), "\n";
}
?>

结果

下面是 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]

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]

除了 xdebug.collect_params 设置，还有其他设置编号会影响跟踪文件的输出。第一个 "default" 标签展示了如上面所示的默认情况。第二个标签 "show_mem_delta" 展示了在输出文件不同的两行之间的内存使用差异。

在 "collect_return=1" 标签上所有函数调用的返回值都是可见的。可以通过 xdebug.collect_return 设置来打开。

"collect_assignments=1" 标签会显示变量参数，这可以用 xdebug.collect_assignments 设置来打开。

最后一个标签展示了一种不同的输出格式，这更加容易解析但是阅读起来会更困难。如果有额外的工具来解释跟踪文件，那么 xdebug.trace_format 设置通常来说是非常有用的。 

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 语法文件

Xdebug 附带了能高亮跟踪文件语法的 VIM 语法文件： xt.vim。为了让 VIM 识别新的格式需要执行下面的步骤：

  1. 复制 xt.vim 文件到 ~/.vim/syntax
  2. 编辑或创建 ~/.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]

折叠也能生效，可以使用 zc 和 zo 来折叠部分跟踪文件。

相关设置

xdebug.auto_trace
类型：布尔值，默认值： 0
当这个设置开启时，在脚本运行之前函数的跟踪调用将会开启。在 auto_prepend_file 中能实现跟踪代码。
xdebug.collect_assignments
类型：布尔值，默认值： 0， 由 Xdebug > 2.1 引入

这个设置默认为 0，控制 Xdebug 是否应该添加变量语句到函数跟踪中。

从 Xdebug 2.6 起，也包括变量赋值 (=&) 语句。

xdebug.collect_includes
类型：布尔值，默认值： 1
这个设置默认为 1，控制 Xdebug 是否应该在 include()，include_once()，require() 或者 require_once() 的文件跟踪中写入文件名。
xdebug.collect_params
类型：整数，默认值： 0

这个设置默认为 0，当一个函数被函数跟踪或堆栈跟踪记录时，控制 Xdebug 是否收集参数传递给函数。

设置默认为 0 是因为非常大型的脚本会消耗巨大的内存，因此这样能让大型脚本运行起来。除了在大量函数调用和（或者）大型数据结构作为参数的脚本，都能最大程度的的安全的开启这个设置。 Xdebug 2 增加内存消耗时不会有这个问题，因为它从不将信息储存在内存中。相反它只会写入磁盘中。这意味着你需要查看磁盘空间使用情况。

这个设置有 4 个不同的值。针对每个值会有不同的信息显示。下面你将会看到每个值提供的信息是什么。也可以看堆栈跟踪特征的介绍提供的一些屏幕截图。

值参数信息显示
0无
1元素的类型和数量 (例如 string(6), array(8))。
2

元素的类型和数量，并附带工具提示显示完整信息1。

3完整变量内容 (内容受限于以下设置 xdebug.var_display_max_children， xdebug.var_display_max_data 和 xdebug.var_display_max_depth。
4完整变量内容和名称。
5PHP 序列化变量内容，不含名称。 (2.3 版本新增)

1 在 PHP 的 CLI 版本中将不会有工具提示，在输出文件中也没有。

xdebug.collect_return
类型：布尔值，默认值： 0

设置默认为 0，控制 Xdebug 是否应该将函数调用的返回值写入跟踪文件。

对于计算机的跟踪文件 （xdebug.trace_format=1） 仅仅只从 Xdebug 2.3 开始工作。

xdebug.show_mem_delta
类型：整数，默认值：0
当这个设置设为其他不等于 0 的值时，Xdebug 会生成易于人类阅读的跟踪文件，将会向显示不同函数调用间内存使用的差异。如果 Xdebug 是配置为生成易于计算机阅读的跟踪文件则将会总是显示这个信息。
xdebug.trace_enable_trigger
类型：布尔值，默认值： 0， 由 Xdebug > 2.2 引入
当这个设置设为 1，可以通过使用 XDEBUG_TRACE GET/POST 参数或者设置一个名为 XDEBUG_TRACE 的会话来触发生成跟踪文件。这将会把跟踪数据写入定义的目录。为了阻止 Xdebug 为每一个请求都生成跟踪文件，你需要设置 xdebug.auto_trace 为 0。可以通过配置 xdebug.trace_enable_trigger_value 来访问触发器本身。
xdebug.trace_enable_trigger_value
类型：字符串，默认值： ""， 由 Xdebug >= 2.3 引入
这个设置可以用来限制在 xdebug.trace_enable_trigger 中谁能利用 XDEBUG_TRACE 功能进行概括。当将它的默认值更改为空字符串时，cookie 的值、GET 或者 POST 参数需要匹配设置在这个设置中的秘钥才能生成跟踪文件
xdebug.trace_format
类型：整数，默认值： 0

跟踪文件的格式：

值描述
0显示供人类可读的跟踪文件： 时间点，内存使用，内存增量 （如果设置 xdebug.show_mem_delta 开启），层级，函数名， 函数参数 （如果设置 xdebug.collect_params 开启）， 文件名和行号。
1用两种不同记录编写记算机可读格式文件。其记录不同在于一个插入堆栈边框，一个移除堆栈边框。以下表格列出记录中每个栏位区别。字段是制表符分隔的。
2使用 HTML 写成跟踪文件。

计算机格式的字段：

Record type123456789101112 - ...
进入 层级 函数 # 总是 '0' 时间点 内存使用 函数名 自定义 (1) 或者内部函数 (0) include/require 的文件名 文件名 行号 参数数量 参数 (与字段 11 中指定的一样多) - 制表符分隔
退出 层级 函数 # 总是 '1' 时间点 内存使用 空
返回 层级 函数 # 总是 'R' 空 返回值 空

查看函数跟踪的介绍的一些示例。

xdebug.trace_options
类型：整数，默认值： 0
当设置为 1，后续请求生成的跟踪文件将被追加而不是改写。
xdebug.trace_output_dir
类型：字符串，默认值： /tmp
跟踪文件将会被写入的目录，需要确保运行 PHP 的用户有权限对这个目录进行写入。
xdebug.trace_output_name
类型：字符串，默认值： trace.%c

这个设置决定了用来转储跟踪信息的文件名。这个设置指定了格式化说明符的格式，非常类似于 sprintf() 和 strftime()。这里有几个格式化说明符可以用来格式化文件名。".xt" 扩展总是会自动添加上。

可能的格式化说明符有：

标识符意义格式范例文件名范例
%c当前工作路径的 crc32 效验值trace.%ctrace.1258863198.xt
%p进程标识符 pidtrace.%ptrace.5174.xt
%r随机数trace.%rtrace.072db0.xt
%s

脚本名 2

cachegrind.out.%scachegrind.out._home_httpd_html_test_xdebug_test_php
%t时间戳（秒）trace.%ttrace.1179434742.xt
%u时间戳（微秒）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 （来自 $_COOKIE，如果有设置）trace.%Strace.c70c1ec2375af58f74b390bbdd2a679d.xt
%%literal %trace.%%trace.%%.xt

2 从 Xdebug 2.6 起，针对跟踪文件名这个是不可用的。

3 版本 2.2 中的新增。这个可以通过 Apache 的 mod_unique_id 模式 修改。

xdebug.var_display_max_children
类型：整数，默认值： 128

当变量通过 xdebug_var_dump() 、 xdebug.show_local_vars 或者函数跟踪显示时，控制数组子元素和对象属性显示的数量。

设置值为 -1 ，可以取消显示的任何限制。

这个设置不会对通过远程调试功能发送到客户端的子元素数量有任何影响。

xdebug.var_display_max_data
类型：整数，默认值： 512

当变量通过 xdebug_var_dump() 、 xdebug.show_local_vars 或者函数跟踪显示时，控制显示的字符串的最大长度。

设置值为 -1 ，可以取消显示的任何限制。

这个设置不会对通过远程调试功能发送到客户端的子元素数量有任何影响。

xdebug.var_display_max_depth
类型：整数，默认值： 3

当变量通过 xdebug_var_dump() 、 xdebug.show_local_vars 或者函数跟踪显示时，控制数组子元素和对象属性嵌套多少层。

你可以选择的最大值是 1023 。你也可以使用 -1 作为值来选择这个最大的值。

这个设置不会对通过远程调试功能发送到客户端的子元素数量有任何影响。

相关函数

string xdebug_get_tracefile_name()
返回函数跟踪的文件名

返回用来跟踪脚本输出的文件名。当 xdebug.auto_trace 开启时这个设置很有用。

string xdebug_start_trace( [ string trace_file [, integer options] ] )
开启一个新的函数跟踪

开启从该函数到 trace_file 参数的文件的跟踪。如果没有函数名指定，那么跟踪文件将会被配置 xdebug.trace_output_dir 设置中的目录替代。

如果文件名作为第一个参数给出，则名字是针对当前工作目录的相对路径。这个当前工作目录可能不同于你所期望的，所以如果要指定一个文件名请使用一个绝对路径。可以使用 PHP 的 getcwd() 函数来计算出当前工作目录是什么。

跟踪文件的名字是 "{trace_file}.xt"。如果 xdebug.auto_trace 开启，那么 "{trace_file}.xt" 在 "{trace_file}" 部分的格式会取决于 xdebug.trace_outpuut_name 的设置。这个 options 是一个位字段，目前有这几种选项：

XDEBUG_TRACE_APPEND (1)
让跟踪文件打开是追加模式而不是覆盖模式 overwrite mode
XDEBUG_TRACE_COMPUTERIZED (2)
创建一个跟踪文件，以 "xdebug.trace_format" 中值为 1 的格式
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 影响跟踪文件的格式。

这个函数会返回 Xdebug 跟踪的文件名和全路径。这可能会是你传递的文件名（潜在的添加 ".xt"），如果没有文件名传递进去就会是自动生成的文件名。

string xdebug_stop_trace()
停止当前函数跟踪

停止跟踪函数调用，关闭跟踪文件。

函数返回跟踪被写入的文件的文件名