README

🔔 订阅 时事通讯，不错过任何关于 Chevere 的更新。

摘要

PHP 客户端库为 xrDebug。此库提供了一系列函数，用于变量转储、发送原始消息和与检查器交互。

VarDump 功能由 VarDump 包提供，而可抛出对象处理则由 ThrowableHandler 包提供。

快速开始

使用 Composer 安装。

composer require --dev xrdebug/php

确保在项目的入口文件（通常是 index.php）中加载 Composer 的 autoload.php 文件。

require_once __DIR__ . '/vendor/autoload.php';

在您的代码中直接使用 xr() 来转储任何变量。例如，对于 WordPress 插件

add_action('plugins_loaded', function () {
    $userCanManageOptions = current_user_can('manage_options');
    xr($userCanManageOptions);
});

演示

在 ./demo 目录中有此库的交互式演示。要使用演示，请使用默认设置执行 xrdebug 服务器。

执行以下命令以启动演示，它将向 xrDebug 服务器发送消息，解释调试器用户界面。

php demo/welcome.php

执行以下命令以查看 xrDebug 如何 处理错误。

php demo/error-handling.php

调试助手

此 xrDebug PHP 客户端在根命名空间中提供了以下辅助函数。您可以在代码的任何位置使用这些函数。

xr

使用函数 xr($var1, $var2,...) 转储一个或多个变量。

xr($var, 'Hola, mundo!');

使用 t: 传递一个主题。

xr($var, t: 'Epic win');

使用 e: 传递一个表情。

xr($var, e: '😎');

传递位运算标志以触发特殊行为。

• 使用 f: XR_BACKTRACE 包括调试回溯。

xr($var, f: XR_BACKTRACE);

xrr

使用函数 xrr() 发送原始消息。

xrr('<h1>Hola, mundo!</h1>');
xrr('<span>Test</span>', t: 'Epic win');
xrr('<b>test</b>', e: '😎');
xrr('some string<br>', f: XR_BACKTRACE);

xri

使用函数 xri() 与检查器交互。

使用 pause 暂停代码执行。

xri()->pause();

使用 memory 发送内存使用信息。

xri()->memory();

vd

函数 vd 是 var_dump 的直接替换，它由 VarDump 包提供。它将一个或多个变量的信息打印到输出流。

vd($var1, $var2,);
// more code

vdd

函数 vdd 与 vd 功能相同，但使用 die(0) 停止进一步执行。

vdd($var);
// does exit();

配置

基于代码的配置

使用 xrConfig() 配置 xrDebug 服务器连接。

xrConfig(
    isEnabled: true,
    isHttps: false,
    host: 'localhost',
    port: 27420,
    key: file_get_contents('private.key')
);

基于文件的配置

通过在项目根目录中放置 xr.php 文件来配置客户端。

我们建议将 xr.php 添加到您的 .gitignore 文件中。

<?php

return [
    'isEnabled' => true,
    'isHttps' => false,
    'host' => 'localhost',
    'port' => 27420,
    'key' => file_get_contents('private.key'),
];

错误处理

要使用 xrDebug 处理错误，您需要配置项目以将错误处理为异常，并注册一个关闭函数

use Chevere\ThrowableHandler\ThrowableHandler;

set_error_handler(
    ThrowableHandler::ERROR_AS_EXCEPTION
);
register_shutdown_function(
    ThrowableHandler::SHUTDOWN_ERROR_AS_EXCEPTION
);

异常处理

PHP 客户端提供了一个可抛出对象处理程序，它可以通过 ThrowableHandler 包挂钩或替换现有的异常处理逻辑。

注册处理器

使用 registerThrowableHandler 启用 xrDebug 异常处理。

use Chevere\xrDebug\PHP\registerThrowableHandler;

// True append xrDebug to your existing handler
// False use only xrDebug handler
registerThrowableHandler(true);

触发处理器

在任何现有的异常处理逻辑中使用 throwableHandler

use Chevere\xrDebug\PHP\throwableHandler;

set_exception_handler(
    function(Throwable $throwable) {
        // ...
        try {
            throwableHandler($throwable);
        } catch(Throwable) {
            // Don't panic
        }
    }
);

自定义检查器

可以定义额外的检查器来提供更多上下文相关的调试信息。要创建自定义检查器，使用 XrInspectorTrait 实现 XrInspectorInterface 并使用 sendCommand 方法。

对于下面的代码，myDump 定义了一个方法，该方法将从您的应用程序逻辑中流式传输数据，而 myPause 默认发送带有调试回溯的暂停。

<?php

use Chevere\xrDebug\PHP\Traits\XrInspectorTrait;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;

class MyInspector implements XrInspectorInterface
{
    use XrInspectorTrait;

    public function myDump(
        string $t = '',
        string $e = '',
        int $f = 0,
    ): void {
        $data = 'my queries from somewhere...';
        $this->sendCommand(
            command: 'message',
            body: $data,
            topic: $t,
            emote: $e,
            flags: $f,
        );
    }

    public function myPause(
        int $f = XR_DEBUG_BACKTRACE,
    ): void {
        $this->sendCommand(
            command: 'pause',
            flags: $f,
        );
    }
}

sendCommand 方法使您能够与现有的 xrDebug 实例进行交互。

private function sendCommand(
    string $command,
    string $body = '',
    string $topic = '',
    string $emote = '',
    int $flags = 0
);

空检查器

如果 xrDebug 未启用，则需要空检查器来阻止任何检查调用。空检查器应该实现与真实检查器相同的方法，但不需要执行任何操作。

💡 使用 XrInspectorNullTrait 来实现 XrInspectorInterface，当提供空检查器时。

<?php

use Chevere\xrDebug\PHP\Traits\XrInspectorNullTrait;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;

class MyInspectorNull implements XrInspectorInterface
{
    use XrInspectorNullTrait;

    public function myDump(
        string $t = '',
        string $e = '',
        int $f = 0,
    ): void {
    }

    public function myPause(
        int $f = XR_DEBUG_BACKTRACE,
    ): void {
    }
}

自定义检查器的辅助函数

use Chevere\xrDebug\PHP\XrInspectorInstance;
use Chevere\xrDebug\PHP\Interfaces\XrInspectorInterface;
use LogicException;
use MyInspector;
use MyInspectorNull;

function my_inspector(): MyInspector
{
    try {
        return XrInspectorInstance::get();
    } catch (LogicException) {
        $inspector = getXr()->enable()
            ? MyInspector::class
            : MyInspectorNull::class;
        $client = getXr()->client();
        $inspector = new $inspector($client);
        $instance = new XrInspectorInstance($inspector);

        return $instance::get();
    }
}

要使用您的自定义辅助函数

my_inspector()->myDump();
my_inspector()->myPause();

文档

文档可在 docs.xrdebug.com 上找到。

许可

版权 Rodolfo Berrios A.

xrDebug 遵循 Apache 许可协议，版本 2.0。有关完整的许可文本，请参阅 LICENSE。

除非适用法律要求或书面同意，否则在许可下分发的软件按“现状”分发，不提供任何明示或暗示的保证或条件。有关许可的具体语言、权限和限制，请参阅许可协议。