README

FiberPHP 框架的 PSR-3 日志库。零框架依赖的纯库实现（仅依赖 psr/log 与 ext-json），内置按天轮转、缓冲刷盘、trace 上下文注入、敏感字段脱敏与多通道管理；在 FiberPHP 框架中由 Kernel 自动注入宿主能力（配置 / 存储路径 / trace 提供者），开箱即用。

环境要求

PHP >= 8.3
ext-json
psr/log ^3.0

框架接入为可选：在 FiberPHP 框架中由 Kernel 的 LogGlue 注入宿主能力并注册 LogProvider，独立使用时无需 fiberphp/container。

安装

composer require fiberphp/log

独立使用（非框架项目）

use FiberPHP\Log\LogManager;

$log = new LogManager(
    [
        'default' => [
            'constructor' => [
                'max_files' => 7,
                'level'     => 'info',
            ],
        ],
    ],
    baseDir: '/var/log/myapp', // 日志存储根目录
);

// PSR-3 标准方法
$log->info('用户登录成功', ['uid' => 1001]);
$log->error('支付失败', ['order_no' => 'A2026']);

// 多通道：不同通道独立文件 / 级别 / 处理器链
$log->channel('db')->debug('SQL', ['sql' => 'select 1']);

日志落盘为 JSON 行（{name}-{YYYY-MM-DD}.log），字段结构对齐 Monolog JsonFormatter，可直接对接 logstash/ELK。

框架内使用

框架应用由 FiberPHP\Log\LogProvider 自动完成容器注册（Kernel 在 master 启动早期与 worker/Console 阶段注入宿主能力），业务代码统一通过 logger() 助手使用：

logger()->info('服务启动', ['workers' => 4]);
logger()->channel('db')->debug('慢查询', ['cost_ms' => 230]);

// PSR-3 {key} 占位符插值（仅标量/ null）
logger()->info('用户 {name} 下单 {count} 件', ['name' => 'tom', 'count' => 3]);

配置位于应用 config/log.php（安装框架后自动发布）：

return [
    // 默认通道（业务通用日志）
    'default' => [
        'constructor' => [
            // path 留空时自动落到 runtime_path()/logs/default-YYYY-MM-DD.log
            'max_files' => 7,      // 最多保留 7 天（0=无限保留）
            'level'     => 'info', // debug/info/notice/warning/error/critical/alert/emergency
        ],
    ],

    // 缓冲刷盘（高 QPS 场景建议开启，默认开）
    'buffer' => [
        'enabled'         => true,  // false = 每条日志同步 fwrite（调试更直观）
        'flush_interval'  => 1.0,   // 秒，Workerman Timer 周期定时刷盘
        'flush_threshold' => 1000,  // 条数，达到上限立即 flush
    ],

    // 敏感字段脱敏（默认开启，递归覆盖数组与普通对象）
    'masking' => [
        'enabled' => true,
        'fields'  => ['password', 'token', 'secret', 'key', 'credential', 'auth', 'passwd',
                      'mobile', 'phone', 'email', 'id_card', 'bank_card'],
        'mask'    => '******',
    ],
];

新增通道只需在 config/log.php 追加同名段（如 'db' => [...]），首次 logger()->channel('db') 时懒加载生效。

特性

能力	说明
按天轮转	`{name}-YYYY-MM-DD.log` 自动切换，`max_files` 过期清理（mkdir 原子锁防多 worker 并发惊群）
持久句柄	文件句柄按路径缓存 + `fstat` 判大小，避免每条日志 fopen/fclose，I/O 系统调用显著减少
非阻塞写	`LOCK_EX \\| LOCK_NB`，锁竞争时直接丢弃，不阻塞事件循环
缓冲刷盘	内存缓冲 + `register_shutdown_function` 兜底 flush；超阈值立即 flush
定时刷盘	Workerman `Timer` 周期刷盘（CLI/无 Timer 环境自动退化为 shutdown flush）
trace 注入	自动合并 `trace_id` / `span_id` / `app_name` 到 extra（宿主经 traceProvider 注入）
敏感脱敏	12 个默认字段递归脱敏（数组/对象），`Throwable` 跳过防循环引用
级别解析	字符串 / Monolog 对齐数值（100–600）/ enum 三态配置兼容
PSR-3 插值	`{key}` 占位符，仅替换标量与 null

自定义 Handler

实现 FiberPHP\Log\Contract\HandlerInterface，在通道配置的 handlers 中挂载即可接入处理器链（如对接 Sentry / Elasticsearch / Kafka）：

use FiberPHP\Log\Contract\HandlerInterface;

class SentryHandler implements HandlerInterface
{
    public function isHandling(array $record): bool
    {
        return $record['level'] >= 400; // error 及以上上报
    }

    public function handle(array $record): bool
    {
        // $record: {message, context, level, channel, datetime, extra, name}
        // ... 上报 Sentry；返回 true 表示已消费，冒泡终止
        return false;
    }

    public function handleBatch(array $records): void {}
    public function close(): void {}
    public function reset(): void {}
}

目录结构

src/Log/
├── Contract/HandlerInterface.php   # 处理器契约
├── Handler/
│   ├── RotatingFileHandler.php     # 按天轮转文件处理器
│   ├── BufferHandler.php           # 缓冲处理器
│   └── BufferedTimedHandler.php    # Timer 周期刷盘缓冲处理器
├── LogLevel.php                    # 级别枚举（Monolog 数值对齐）
├── LogManager.php                  # 多通道管理器（PSR-3 + 链式 channel()）
├── LogProvider.php                 # 容器注册（宿主槽位注入）
└── Processors.php                  # trace 注入 / 敏感脱敏

fiberphp / log

Maintainers

Package info

Statistics

Security