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 找到。

许可证

xrDebug 采用 Apache License，版本 2.0 许可。有关完整的许可文本，请参阅 LICENSE。

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

xrdebug / php

维护者

详细信息