xuchunyang/ray-think

Ray debugging client for ThinkPHP 8

dev-main 2026-05-11 17:25 UTC

Requires

• php: >=8.0
• topthink/framework: ^8.0

MIT

• xuchunyang

• debug
• laravel
• thinkphp
• ray

README

ThinkPHP 8 的 Ray 调试客户端。配合 Ray Server 使用。

安装

composer require xuchunyang/ray-think

服务会自动注册（通过 extra.think.services 自动发现）。

配置

发布配置文件（可选）：

php think vendor:publish xuchunyang/ray-think

或手动创建 config/ray.php：

return [
    'enabled' => env('ray.enabled', app()->isDebug()),
    'server_url' => env('ray.server_url', 'http://127.0.0.1:23517'),
    'timeout' => 0.5,
    'sensitive_keys' => ['password', 'token', 'secret'],
    'middleware_enabled' => true,
];

环境变量：

RAY_ENABLED=true
RAY_SERVER_URL=http://127.0.0.1:23517
RAY_TIMEOUT=0.5

使用

基础输出

// 普通日志
ray('hello world');
ray($user, $data, $config);

// JSON
ray()->json(['id' => 1, 'name' => 'Tom'], 'User Info');

// 表格
ray()->table([
    ['name' => 'Alice', 'score' => 95],
    ['name' => 'Bob', 'score' => 82],
], 'Exam Results');

// SQL
ray()->sql('SELECT * FROM users WHERE id = ?', [1], 12.5, 'mysql');

// 异常
try { ... } catch (\Throwable $e) {
    ray()->exception($e);
}

// 图片
ray()->image('https://example.com/chart.png');
ray()->image('/tmp/debug.png');  // 本地文件自动转 base64

链式调用

// 颜色
ray('success')->green();
ray('warning')->orange();
ray('error')->red();
ray('info')->blue();
ray('special')->purple();
ray('muted')->gray();
ray('alert')->yellow();

// 标签
ray('deployed!')->label('Deploy');

// 大小
ray('debug info')->small();
ray('important!')->large();

// 组合
ray('Server is down!')->red()->label('Critical')->small();
ray(['status' => 'ok'])->green()->label('Health Check');
ray()->table($data)->orange()->label('Slow Queries');

Screen 分组

ray()->screen('用户模块');
ray('这条消息在用户模块下');

ray()->screen('订单模块');
ray('这条消息在订单模块下');

辅助函数

ray('hello');           // 输出
ray()->json($data);     // 链式
ray_screen('模块名');    // 切换分组
ray_clear();            // 清空

自动功能

• 请求/响应记录：中间件自动记录每个 HTTP 请求和响应
• SQL 监听：自动捕获数据库查询
• 敏感字段脱敏：password、token、api_key 等自动替换为 ***
• 生产环境禁用：APP_DEBUG=false 时完全跳过，零开销
• 快速失败：Server 不可达时，5秒内跳过后续请求，不卡业务

生产环境

APP_DEBUG=false 时，Ray 完全禁用：

• ray() 调用直接返回空对象
• 不走容器、不创建对象、不发 HTTP
• 4万次调用耗时约 8ms，每次 0.0002ms

配合服务端使用

启动 Ray Server：

cd ray-server
./ray-server

然后在 ThinkPHP 项目中使用 ray() 即可。

License

MIT