README

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

摘要

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

VarDump 功能由 VarDump 包提供，而可抛出异常由 ThrowableHandler 包处理。

快速开始

使用 Composer 安装。

composer require --dev xrdebug/php

请确保在项目入口文件中加载 Composer 的 autoload.php 文件，通常位于 index.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 禁用的情况下，需要一个空检查器来避免任何检查调用 （如果 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 License，版本 2.0 许可。请参阅 LICENSE 了解完整的许可文本。

除非适用法律要求或书面同意，否则根据许可分发软件时，按“原样”提供，不提供任何明示或暗示的保证或条件。请参阅许可协议了解具体的管理权限和限制。