PHPackages                             colinwoo/webman-error-logger - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. colinwoo/webman-error-logger

ActiveLibrary[Logging & Monitoring](/categories/logging)

colinwoo/webman-error-logger
============================

Webman error logger plugin - automatically log API errors to database

v1.0.0(6mo ago)013MITPHPPHP >=8.1

Since Dec 8Pushed 6mo agoCompare

[ Source](https://github.com/Colin9R/webman-error-logger)[ Packagist](https://packagist.org/packages/colinwoo/webman-error-logger)[ RSS](/packages/colinwoo-webman-error-logger/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (2)Versions (2)Used By (0)

Webman Error Logger
===================

[](#webman-error-logger)

一个功能强大的 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
```

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

1. 在 `config/middleware.php` 中注册中间件
2. 创建配置文件 `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,
];
```

### 配置说明

[](#配置说明)

**关键配置项:**

1. **`rethrow_exception`** (重要!)

    - `false` (推荐): 捕获所有异常并返回友好错误响应，用户会收到错误提示
    - `true`: 记录日志后继续抛出异常，可能导致用户无感知错误（如您遇到的 ErrorException 问题）
2. **`show_error_details`**

    - `true`: 在错误响应中包含详细堆栈信息（开发环境推荐）
    - `false`: 只返回简单错误消息（生产环境推荐）
3. **`table_prefix`**

    - 如果您的项目使用表前缀（如 `omnix_`），在此配置
    - 最终表名为: `{table_prefix}{table_name}`
4. **`ignore_exceptions`**

    - 可以忽略特定类型的异常，避免记录过多日志
    - 支持异常类继承关系判断

### 推荐配置

[](#推荐配置)

**开发环境:**

```
return [
    'enable' => true,
    'dev_only' => false,
    'rethrow_exception' => false,
    'show_error_details' => true,  // 显示详细错误信息
    'error_response' => [
        'success' => false,
        'message' => '系统错误，请稍后重试',
        'code' => 500,
    ],
];
```

**生产环境:**

```
return [
    'enable' => true,
    'dev_only' => false,
    'rethrow_exception' => false,
    'show_error_details' => false,  // 隐藏详细错误信息
    'ignore_exceptions' => [
        'support\exception\BusinessException',  // 忽略业务异常
    ],
    'error_response' => [
        'success' => false,
        'message' => '系统繁忙，请稍后再试',
        'code' => 500,
    ],
];
```

### 解决 ErrorException 问题

[](#解决-errorexception-问题)

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

1. 设置 `'rethrow_exception' => false`
2. 这样错误会被记录到数据库，同时返回友好错误给前端
3. 开发环境可设置 `'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
```

卸载时会自动:

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

技术支持
----

[](#技术支持)

- GitHub:
- Issues:

许可证
---

[](#许可证)

MIT License

注意事项
----

[](#注意事项)

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

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance66

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

199d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6fee1ef400b5df350a224c86e2d4e086d668f97caeec84b933742dab2cb6c478?d=identicon)[ColinWoo](/maintainers/ColinWoo)

---

Top Contributors

[![Colin9R](https://avatars.githubusercontent.com/u/15063105?v=4)](https://github.com/Colin9R "Colin9R (7 commits)")

### Embed Badge

![Health badge](/badges/colinwoo-webman-error-logger/health.svg)

```
[![Health](https://phpackages.com/badges/colinwoo-webman-error-logger/health.svg)](https://phpackages.com/packages/colinwoo-webman-error-logger)
```

###  Alternatives

[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M153](/packages/spatie-laravel-health)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[directorytree/metrics

Record metrics in your Laravel application

27147.7k](/packages/directorytree-metrics)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)