Xdebug 之远程调试

发表于 2016-10-22 分类于 PHP Changyan：本文字数： 7.1k 阅读时长 ≈ 6 分钟

Xdebug 为与运行 PHP 脚本交互的调试器客户端提供了一个接口。本节介绍如何设置 PHP 和 Xdebug 来允许这一点，并介绍一些客户端。

介绍

Xdebug 的（远程）调试器允许您检查数据结构，交互式地浏览和调试您的代码。正在使用的协议是打开的，称为 DBGp。此协议在 Xdebug 2 中实现，并替换不再支持的旧的 GDB 类协议。

客户端

Xdebug 2 捆绑了一个用于 DBGp 协议的简单命令行客户端。还有一些其他客户端实现（免费和商业）。我不是任何这些的作者，所以请参考原作者的支持：

Dev-PHP (IDE: Windows)
Eclipse plugin (IDE).
Emacs plugin (Editor Plugin).
KDevelop (IDE: Linux (KDE); Open Source).
ActiveState’s Komodo (IDE: Windows, Linux, Mac; Commercial).
MacGDBP (Standalone client for Mac OS X; Free)
NetBeans (IDE: Windows, Linux, Mac OS X and Solaris).
Notepad++ plugin (Editor: Windows).
WaterProof’s PHPEdit (IDE, from version 2.10: Windows; Commercial).
PHPEclipse (Editor Plugin).
Devsense’s PHP Tools for Visual Studio (MS Visual Studio Plugin; Commercial).
JetBrain’s PhpStorm (IDE; Commercial).
Protoeditor (Editor: Linux).
pugdebug (Standalone client for Linux, Windows and Mac OS X; Open Source).
VIM plugin (Editor Plugin).
jcx software’s VS.Php (MS Visual Studio Plugin; Commercial).
Xdebug Chrome App (Chrome Application; Open Source)
XDebugClient (Standalone client for Windows).

用于调试的简单命令行客户机与 debugclient 目录中的 Xdebug 捆绑在一起。

启动调试器

为了启用 Xdebug 的调试器，您需要在 php.ini 中进行一些配置设置。这些设置为 xdebug.remote_enable 以启用调试器 xdebug.remote_host 和 xdebug.remote_port 来配置调试器应连接到的 IP 地址和端口。还有一个 xdebug.remote_connect_back 设置，如果您的开发服务器与多个开发人员共享，则可以使用此设置。

如果希望调试器在发生错误情况（PHP 错误或异常）时启动会话，则还需要更改 xdebug.remote_mode 设置。此设置的允许值为 “req”（默认值），这使得调试器在脚本启动时启动会话，或者 “jit”，当会话只应在错误时启动。

完成所有这些设置后，Xdebug 仍然不会在脚本运行时自动启动调试会话。你需要激活 Xdebug 的调试器，你可以通过三种方式：

1、当从命令行运行脚本时，您需要设置一个环境变量，如：

export XDEBUG_CONFIG="idekey=session_name"
php myscript.php

您还可以在此相同的环境变量中配置 xdebug.remote_host，xdebug.remote_port，xdebug.remote_mode 和 xdebug.remote_handler，只要使用空格分隔值即可：

export XDEBUG_CONFIG="idekey=session_name remote_host=localhost profiler_enable=1"

通过 XDEBUG_CONFIG 设置可以获得的所有设置也可以使用正常的 php.ini 设置进行设置。

2、如果要调试通过 Web 浏览器启动的脚本，只需将 XDEBUG_SESSION_START = session_name 作为参数添加到 URL。而不是使用 GET 参数，您还可以将 XDEBUG_SESSION_START 设置为 POST 参数，或通过 cookie。请参阅下一节，了解调试会话如何在浏览器窗口中工作。

3、通过 Web 服务器运行 PHP 时激活调试器的另一种方法是安装以下四个浏览器扩展之一。它们中的每一个都允许您通过单击一个按钮来启用调试器。当这些扩展是活动的，他们直接设置 XDEBUG_SESSION cookie，而不是通过 XDEBUG_SESSION_START 进一步的 HTTP 调试会话中描述。扩展名为：

The easiest Xdebug

这个扩展的 Firefox 是为了使 IDE 的调试更容易。您可以在 https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/ 找到扩展程序。
Xdebug Helper for Chrome

Chrome 的此扩展程序将帮助您通过一次点击启用 / 禁用调试和分析。您可以在 https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc 找到扩展程序。
Xdebug Toggler for Safari

Safari 的这个扩展允许你从 Safari 中自动启动 Xdebug 调试。你可以从 Github https://github.com/benmatselby/xdebug-toggler 获取它。
Xdebug launcher for Opera

这个扩展的 Opera 允许您从 Opera 启动 Xdebug 会话。

在你开始你的脚本之前，你需要告诉你的客户端它可以接收调试连接，请参考具体客户端的文档如何做到这一点。要使用捆绑的客户端，只需在编译和安装后启动它。您可以通过运行 “debugclient” 启动它。

当 debugclient 启动时，它将显示以下信息，然后等待，直到调试服务器启动连接：

Xdebug Simple DBGp client (0.10.0)
Copyright 2002-2007 by Derick Rethans.
- libedit support: enabled

Waiting for debug server to connect.

在建立连接后，将显示调试服务器的输出：

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)

现在，您可以使用 DBGp 文档页面中说明的命令集。当脚本结束时，调试服务器与客户端断开连接，并且调试客户端在等待新连接时恢复。

通讯建立

使用静态 IP / 单个开发者

通过远程调试，嵌入在 PHP 中的 Xdebug 就像客户端，而 IDE 作为服务器。以下动画显示了通信通道的设置：

img

服务器的 IP 是 10.0.1.2，HTTP 在端口 80 上
IDE 在 IP 10.0.1.42 上，因此 xdebug.remote_host 设置为 10.0.1.42
IDE 侦听端口 9000，因此 xdebug.remote_port 设置为 9000
HTTP 请求在运行 IDE 的计算机上启动
Xdebug 连接到 10.0.1.42:9000
调试运行，提供 HTTP 响应

与未知 IP / 多开发者

如果使用 xdebug.remote_connect_back，设置稍有不同：

img

服务器的 IP 是 10.0.1.2，HTTP 在端口 80 上
IDE 处于未知 IP，因此 xdebug.remote_connect_back 设置为 1
IDE 侦听端口 9000，因此 xdebug.remote_port 设置为 9000
发出 HTTP 请求后，Xdebug 将从 HTTP 头中检测 IP 地址
Xdebug 连接到端口 9000 上检测到的 IP（10.0.1.42）
调试运行，提供 HTTP 响应

HTTP 调试会话

Xdebug 包含通过浏览器启动时跟踪调试会话的功能：Cookie。这是这样工作：

当 URL 变量 XDEBUG_SESSION_START = name 附加到 URL 或通过具有相同名称的 POST 变量时，-Xdebug 会发出名为 “XDEBUG_SESSION” 的 cookie，并将值设置为 XDEBUG_SESSION_START URL 参数的值。 cookie 的到期时间为 1 小时。当连接到 “idekey” 属性中的 debugclient 时，DBGp 协议也将此相同的值传递给 init 包。
当有一个 GET（或 POST）变量 XDEBUG_SESSION_START 或 XDEBUG_SESSION cookie 被设置时，Xdebug 将尝试连接到一个调试客户端。
要停止调试会话（并销毁 cookie），只需添加 URL 参数 XDEBUG_SESSION_STOP 即可。 Xdebug 将不再尝试连接到调试客户端。

多用户调试

Xdebug 仅允许您在执行远程调试时指定一个 IP 地址与 xdebug.remote_host 连接。它不会自动连接回浏览器运行的计算机的 IP 地址，除非您使用 xdebug.remote_connect_back。

如果所有开发人员在同一（开发）服务器上的不同项目上工作，则可以通过 Apache 的.htaccess 功能为每个目录设置 xdebug.remote_host 设置，方法是使用 php_value xdebug.remote_host = 10.0.0.5。但是，对于多个开发人员在同一代码上工作的情况，.htaccess 技巧不工作，因为代码所在的目录是相同的。

有两个解决方案。首先，你可以使用 DBGp 代理。有关如何使用此代理的概述，请参阅多个用户调试中的文章。您可以在 ActiveState 的网站上下载代理作为 python 远程调试包的一部分。 Komodo FAQ 中还有一些文档。

其次，您可以使用 Xdebug 2.1 中引入的 xdebug.remote_connect_back 设置。

实施细则

Xdebug 的 DBGp 协议的 context_names 命令的实现不依赖于栈级别。在每个调试器会话期间返回的值总是相同的，因此，可以安全地缓存。

相关的设置

xdebug.extended_info

类型：整数，默认值：1

控制 Xdebug 是否应该为 PHP 解析器强制执行’extended_info’模式；这允许 Xdebug 使用远程调试器执行文件 / 行断点。当跟踪或剖析脚本时，通常希望关闭此选项，因为 PHP 生成的 oparrays 将增加大约三分之一的大小减慢脚本。此设置不能在带有 ini_set（）的脚本中设置，但只能在 php.ini 中设置。

xdebug.idekey

类型：字符串，默认值：* complex *

控制哪个 IDE 密钥 Xdebug 应该传递到 DBGp 调试器处理程序。默认值基于环境设置。首先查询环境设置 DBGP_IDEKEY，然后查询 USER 和最后一个 USERNAME。默认值设置为找到的第一个环境变量。如果找不到，则设置为默认的 “”。如果设置此设置，它始终覆盖环境变量。

xdebug.remote_addr_header

类型：字符串，默认值：“”，在 Xdebug> 2.4 中引入

如果 xdebug.remote_addr_header 配置为非空字符串，那么该值将用作 $ SERVER 超全局数组中的键，以确定用于查找用于 “连接回” 的 IP 地址或主机名的头。此设置仅与 xdebug.remote_connect_back 结合使用，否则将被忽略。

xdebug.remote_autostart

类型：布尔值，默认值：0

通常，您需要使用特定的 HTTP GET / POST 变量来启动远程调试（请参阅远程调试）。当此设置设置为 1 时，Xdebug 将始终尝试启动远程调试会话并尝试连接到客户端，即使 GET / POST / COOKIE 变量不存在。

xdebug.remote_connect_back

类型：boolean，默认值：0，在 Xdebug> 2.1 中引入

如果启用，xdebug.remote_host 设置将被忽略，Xdebug 将尝试连接到发出 HTTP 请求的客户端。它检查 $_SERVER [‘HTTP_X_FORWARDED_FOR’] 和 $_SERVER [‘REMOTE_ADDR’] 变量以找出要使用的 IP 地址。

如果配置了 xdebug.remote_addr_header，那么将在 $_SERVER [‘HTTP_X_FORWARDED_FOR’] 和 $_SERVER [‘REMOTE_ADDR’] 变量之前检查具有配置名称的 $ SERVER 变量。

此设置不适用于通过 CLI 进行调试，因为 $ SERVER 标题变量在那里不可用。

请注意，没有可用的过滤器，任何可以连接到 Web 服务器的人都能够启动调试会话，即使他们的地址与 xdebug.remote_host 不匹配。

类型：整数，默认值：3600，在 Xdebug> 2.1 中引入

此设置可用于增加（或减少）远程调试会话通过会话 cookie 保持活动的时间。

xdebug.remote_enable

类型：布尔值，默认值：0

此开关控制 Xdebug 是否应尝试联系正在侦听主机上的调试客户端，并使用设置 xdebug.remote_host 和 xdebug.remote_port 设置的端口。如果无法建立连接，脚本将继续，就像此设置为 0。

xdebug.remote_handler

类型：字符串，默认值：dbgp

可以是 “php3” 选择旧的 PHP 3 式调试器输出，“gdb” 启用 GDB 像调试器接口或’dbgp’ - 调试器协议。 DBGp 协议是唯一支持的协议。

注意：Xdebug 2.1 和更高版本只支持’dbgp’作为协议。

xdebug.remote_host

类型：字符串，默认值：localhost
选择运行调试客户端的主机，您可以使用主机名或 IP 地址。如果启用 xdebug.remote_connect_back，将忽略此设置。

xdebug.remote_log

类型：字符串，默认值：

如果设置为某个值，则将其用作所有远程调试器通信记录到的文件的文件名。该文件始终以附加模式打开，因此默认情况下不会被覆盖。没有可用的并发保护。该文件的格式如下：

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

类型：字符串，默认值：req

选择启动调试连接的时间。此设置可以有两个不同的值：

req

一旦脚本启动，Xdebug 将尝试连接到调试客户端。
jit

Xdebug 只会在出现错误情况时尝试连接到调试客户端。

xdebug.remote_port

类型：整数，默认值：9000

Xdebug 尝试在远程主机上连接的端口。端口 9000 是客户端和捆绑的 debugclient 的默认值。由于许多客户端使用此端口号，最好保持此设置不变。

行云流水

Xdebug 之远程调试

介绍

客户端

启动调试器

通讯建立

使用静态 IP / 单个开发者

与未知 IP / 多开发者

HTTP 调试会话

多用户调试

实施细则

相关的设置

xdebug.extended_info

xdebug.idekey

xdebug.remote_addr_header

xdebug.remote_autostart

xdebug.remote_connect_back

xdebug.remote_enable

xdebug.remote_handler

xdebug.remote_host

xdebug.remote_log

xdebug.remote_mode

xdebug.remote_port

相关函数

bool xdebug_break（）

介绍

客户端

启动调试器

通讯建立

使用静态 IP / 单个开发者

与未知 IP / 多开发者

HTTP 调试会话

多用户调试

实施细则

相关的设置

xdebug.extended_info

xdebug.idekey

xdebug.remote_addr_header

xdebug.remote_autostart

xdebug.remote_connect_back

xdebug.remote_cookie_expire_time

xdebug.remote_enable

xdebug.remote_handler

xdebug.remote_host

xdebug.remote_log

xdebug.remote_mode

xdebug.remote_port

相关函数

bool xdebug_break（）