README

简洁的 Hyperf 全局辅助函数，包含日志、容器、HTTP、缓存等常用能力。

安装

composer require felo-z/hyperf-helper

要求

PHP >= 8.2
Hyperf >= 3.2

函数列表

日志

函数	说明
`error()`	记录 error 日志
`warning()`	记录 warning 日志
`info()`	记录 info 日志
`debug()`	记录 debug 日志
`error_bt()` / `warning_bt()` / `info_bt()` / `debug_bt()`	强制记录调用位置（backtrace）

info('用户登录成功', $userId);
error('签到异常', $exception, ['id' => 1]);

// 单条日志需要定位调用来源
info_bt('订单创建', $orderId);

// 或通过环境变量全局开启（见下方）

backtrace 调用位置

日志 context 中会追加 backtrace 字段，格式为 文件路径:行号。

方案 A：环境变量（默认关闭）

LOG_BACKTRACE=true

开启后，info() / error() 等所有日志函数都会自动带上调用位置。生产环境建议保持 false。

方案 B：显式调用 *_bt() 函数

info_bt('需要定位的日志', $data);
error_bt('临时排查', $exception);

仅当前这条日志记录 backtrace，不受环境变量影响（始终开启）。

容器

函数	说明
`app()`	从容器获取/创建实例，无参时返回容器本身
`resolve()`	`app()` 别名

$service = app(SomeService::class);
$container = app();

命令

函数	说明	需要
`command()`	编程式执行控制台命令	`hyperf/command`

$exitCode = command('migrate', ['--force' => true]);

call()、data_get() 等通用助手由 hyperf/helper 提供，本包不再重复定义。

HTTP

函数	说明	需要
`request()`	获取请求实例或输入参数	`hyperf/http-server`
`response()`	构建响应	`hyperf/http-server`, `hyperf/http-message`
`cookie()`	创建 Cookie 或获取 CookieJar	`hyperf/http-message`
`get_client_ip()`	获取客户端 IP	`hyperf/http-server`

$name = request('name', 'default');
return response(['code' => 0], 200);

缓存 / 会话 / 事件 / 验证

函数	说明	需要
`cache()`	读写缓存	`hyperf/cache`
`session()`	读写 Session	`hyperf/session`
`event()`	派发事件	`hyperf/event`
`validator()`	创建验证器	`hyperf/validation`

工具

函数	说明
`base_path()`	获取项目根路径（需 `BASE_PATH` 常量）
`blank()` / `filled()`	判断值是否为空
`key_filled()`	判断数组 key 存在且值不为空
`is_local()` / `is_pro()`	判断是否为测试/生产环境
`app_env()`	获取 `APP_ENV` 配置值
`throw_if()` / `throw_unless()`	条件抛出异常
`transform()` / `when()` / `rescue()`	条件处理
`fluent()`	创建 Fluent 对象
`object_get()`	点号访问对象属性
`class_namespace()`	获取类命名空间
`literal()`	创建匿名对象
`preg_replace_array()`	按序替换正则匹配
`microseconds()` / `milliseconds()` / `months()` / `weeks()`	Carbon 时间间隔

key_filled / 环境判断

$data = ['name' => 'Tom', 'age' => null, 'tags' => []];

key_filled($data, 'name');  // true
key_filled($data, 'age');   // false（值为 null）
key_filled($data, 'tags');  // false（空数组）
key_filled($data, 'email'); // false（key 不存在）

// 支持嵌套 key
key_filled($data, 'user.name');

// 环境判断（读取 APP_ENV）
app_env();   // dev / test / prod ...
is_local();  // dev、local、test、testing 返回 true
is_pro();    // prod、production 返回 true

日志格式化

日志额外参数会以 data_0, data_1, data_2 ... 的 key 存入 context：

类型	处理方式
Throwable	提取 class, message, code, file:line, trace(前5层)
DateTimeInterface	格式化为 `Y-m-d H:i:s`
BackedEnum	取 `->value`
UnitEnum	取 `->name`
Object (有 toArray)	调用 `toArray()`
Object (无 toArray)	`get_object_vars()`
Array	原样保留
Bool	转为 `'true'` / `'false'`
Null	转为 `'null'`
标量	原样保留

{
  "message": "签到异常",
  "context": {
    "data_0": {
      "class": "RuntimeException",
      "message": "签到服务超时",
      "code": 500,
      "file": "/app/Service/CheckinService.php:42",
      "trace": ["..."]
    }
  }
}

可选依赖

部分函数需要额外安装 Hyperf 组件，详见 composer.json 的 suggest 字段。

致谢

本包中部分辅助函数的设计与实现参考了 friendsofhyperf/helpers，感谢 FriendsOfHyperf 社区的贡献。

felo-z/hyperf-helper

包简介

关键字：

README 文档