README

一个功能强大的 Webman 错误日志记录插件,自动捕获并记录 API 请求错误到数据库,帮助开发者快速定位和排查问题。

核心特性

🎯 自动错误捕获

异常捕获: 自动捕获所有未处理的异常(Exception)
业务异常: 智能识别并记录业务异常(BusinessException),包括验证错误
HTTP 错误: 捕获 4xx/5xx 状态码的错误响应
错误响应: 自动检测 success: false 的 JSON 响应

📝 详细日志记录

请求信息: 记录请求方法(GET/POST/PUT等)、完整URL、所有请求参数
错误详情: 记录错误消息、完整堆栈跟踪,便于问题定位
用户上下文: 自动获取用户ID(支持Session/JWT/Request属性)
客户端信息: 记录真实IP地址、User Agent
时间戳: 精确到秒的错误发生时间

⚙️ 灵活配置

开关控制: 可随时启用/禁用日志记录
环境限制: 支持仅在开发环境启用
异常过滤: 可配置忽略特定类型的异常
路径过滤: 可配置忽略特定URL路径(如健康检查接口)

🚀 开箱即用

一键安装: Composer 安装后自动配置中间件
自动迁移: 提供完整的数据库迁移文件
零侵入: 无需修改现有代码,安装即可使用
自动卸载: 卸载时自动清理配置文件

快速开始

安装

composer require colinwoo/webman-error-logger

安装完成后,插件会自动:

在 config/middleware.php 中注册中间件
创建配置文件 config/plugin/error-logger/config.php

数据库迁移

vendor/bin/phinx migrate -c vendor/colinwoo/webman-error-logger/phinx.php

重启服务

php start.php restart

完成!现在所有错误都会自动记录到 fx_debug_log 表。

配置(可选)

编辑 config/plugin/error-logger/config.php:

return [
    // 是否启用错误日志记录
    'enable' => true,

    // 是否只在开发环境启用
    'dev_only' => false,

    // 数据表名（不含前缀）
    'table_name' => 'debug_log',

    // 数据表前缀（可选，如 'omnix_'）
    'table_prefix' => '',

    // 忽略的异常类型（完整类名）
    'ignore_exceptions' => [
        // 'support\exception\BusinessException', // 业务异常可以选择不记录
        // 'ErrorException', // PHP 错误转换的异常
    ],

    // 忽略的URL路径（支持通配符）
    'ignore_paths' => [
        '/health',
        '/ping',
    ],

    // 是否在捕获异常后继续抛出
    // true: 记录日志后继续抛出异常（默认行为，可能导致前端无感知错误）
    // false: 记录日志后返回友好错误响应给前端
    'rethrow_exception' => false,

    // 错误响应格式（当 rethrow_exception = false 时使用）
    'error_response' => [
        'success' => false,
        'message' => '系统错误，请稍后重试',
        'code' => 500,
    ],

    // 是否在错误响应中包含详细错误信息（仅开发环境建议开启）
    'show_error_details' => false,
];

配置说明

关键配置项:

rethrow_exception (重要!)
- false (推荐): 捕获所有异常并返回友好错误响应，用户会收到错误提示
- true: 记录日志后继续抛出异常，可能导致用户无感知错误（如您遇到的 ErrorException 问题）
show_error_details
- true: 在错误响应中包含详细堆栈信息（开发环境推荐）
- false: 只返回简单错误消息（生产环境推荐）
table_prefix
- 如果您的项目使用表前缀（如 omnix_），在此配置
- 最终表名为: {table_prefix}{table_name}
ignore_exceptions
- 可以忽略特定类型的异常，避免记录过多日志
- 支持异常类继承关系判断

解决 ErrorException 问题

如果您遇到 ErrorException: Implicit conversion from float-string "13.40" to int 类型的错误，只被记录到日志文件但前端无感知的问题，请确保：

设置 'rethrow_exception' => false
这样错误会被记录到数据库，同时返回友好错误给前端
开发环境可设置 'show_error_details' => true 查看详细错误信息

数据表结构

debug_log 表字段:

id - 主键
request_method - 请求方法(GET/POST等)
request_url - 请求URL
request_params - 请求参数(JSON格式)
error_message - 错误信息
error_trace - 错误堆栈
user_id - 用户ID
ip - IP地址
user_agent - User Agent
created_at - 创建时间

查询错误日志

-- 查看最近的错误
SELECT * FROM fx_debug_log ORDER BY created_at DESC LIMIT 20;

-- 按URL统计错误次数
SELECT request_url, COUNT(*) as count
FROM fx_debug_log
GROUP BY request_url
ORDER BY count DESC;

-- 查看特定用户的错误
SELECT * FROM fx_debug_log WHERE user_id = 123;

使用场景

开发调试

快速定位接口报错位置
查看完整的错误堆栈信息
分析用户请求参数

生产监控

实时监控线上错误
统计高频错误接口
追踪特定用户的错误

问题排查

保留历史错误记录
对比不同时间段的错误
分析错误趋势

卸载

composer remove colinwoo/webman-error-logger

卸载时会自动:

从 config/middleware.php 移除中间件配置
删除配置文件 config/plugin/error-logger/
数据表需手动删除: DROP TABLE fx_debug_log;

技术支持

GitHub: https://github.com/Colin9R/webman-error-logger
Issues: https://github.com/Colin9R/webman-error-logger/issues

许可证

MIT License

注意事项

建议定期清理旧的错误日志,避免数据表过大
生产环境可配置 ignore_exceptions 忽略业务异常
请求参数会完整记录,注意敏感信息(如密码)的安全性
建议配合日志分析工具使用,提升问题排查效率

colinwoo/webman-error-logger

包简介

README 文档