# tpglog

**Repository Path**: teemitop/tpglog

## Basic Information

- **Project Name**: tpglog
- **Description**: 一个用于将ThinkPHP应用程序异常记录到数据库的Composer包。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TPGLog - ThinkPHP Exception Logger

一个用于将ThinkPHP应用程序异常记录到数据库的Composer包。

## 功能特性

- 自动捕获并记录应用程序中的所有异常
- 将异常信息存储到数据库中便于分析
- 记录详细的请求和服务器上下文信息
- 提供异常日志查询和统计服务
- 支持按需清理旧的日志记录

## 安装

```bash
composer require teemitop/tpglog
```

> **注意**：如果遇到安装问题，可以先添加 Gitee 的 Composer 镜像源：
> ```bash
> composer config -g repo.packagist composer https://packagist.phpcomposer.com
> ```

## 配置

### 1. 运行数据库迁移

安装包后，需要运行以下命令创建异常日志表：

```bash
php think migrate:run --path=vendor/teemitop/tpglog/migrations
```

如果上述命令因路径问题无法执行，你也可以尝试复制迁移文件到你的项目迁移目录：

```bash
copy vendor\teemitop\tpglog\migrations\20241011000001_install_create_exception_log.php database\migrations\
```

然后执行：

```bash
php think migrate:run
```

> **注意**: 如果您的项目中尚未安装 `topthink/think-migration`，请先安装：
>
> ```bash
> composer require topthink/think-migration
> ```

### 2. 配置异常处理器

在你的 `app/` 下面新建provider.php，并绑定异常处理类：

```php
<?php

// +----------------------------------------------------------------------
// | 服务提供者配置
// +----------------------------------------------------------------------

return [
    // 绑定自定义异常处理handle类
    'think\exception\Handle' => '\\Teemitop\\Tpglog\\ExceptionHandler',
];
```

### 3. 发布配置文件（可选）

将配置文件复制到应用目录：

```bash
cp vendor/teemitop/tpglog/config/exception_logger.php config/
```

## 使用方法

### 基础用法

安装并配置完成后，所有异常将自动记录到数据库的 `exception_log` 表中。

### 手动记录异常

```php
use Teemitop\Tpglog\Services\ExceptionLogService;

try {
    // 一些可能会抛出异常的代码
    throw new \Exception('测试异常');
} catch (\Throwable $exception) {
    // 手动记录异常
    ExceptionLogService::logException($exception, [
        'custom_field' => 'custom_value'
    ]);
}
```

### 查询异常日志

```php
use Teemitop\Tpglog\Services\ExceptionLogService;

// 获取最近20条异常日志
$recentLogs = ExceptionLogService::getRecentLogs(20);

// 搜索特定异常
$searchResult = ExceptionLogService::searchLogs([
    'class' => 'PDOException',
    'date_from' => '2023-01-01',
    'date_to' => '2023-12-31'
]);

// 获取异常统计
$stats = ExceptionLogService::getStatistics(7); // 最近7天的统计
```

### 清理旧日志

```php
use Teemitop\Tpglog\Services\ExceptionLogService;

// 清理30天前的异常日志
$deletedCount = ExceptionLogService::cleanOldLogs(30);
```

## 配置选项

配置文件位于 `config/exception_logger.php`：

```php
return [
    // 是否启用异常日志记录
    'enabled' => true,
    
    // 日志保留天数
    'retention_days' => 30,
    
    // 是否记录特定类型的异常
    'log_http_exceptions' => true,
    'log_route_not_found' => false,
    
    // 是否记录请求数据
    'log_request_data' => true,
    
    // 是否记录服务器数据
    'log_server_data' => true,
    
    // 敏感数据过滤 - 在记录时会被隐藏的字段
    'sensitive_fields' => [
        'password',
        'pwd',
        'secret',
        'token',
        'authorization',
        'cookie',
    ],
    
    // 日志级别
    'level' => 'error',
    
    // 是否同时记录到文件
    'also_log_to_file' => true,
];
```

## 数据库表结构

创建的 `exception_log` 表包含以下字段：

- `id` - 主键
- `class` - 异常类名
- `code` - 异常代码
- `message` - 异常消息
- `file` - 异常发生文件
- `line` - 异常发生行号
- `trace` - 堆栈跟踪
- `request_data` - 请求数据
- `server_data` - 服务器数据
- `request_method` - 请求方法
- `request_uri` - 请求URI
- `user_ip` - 用户IP
- `user_agent` - 用户代理
- `created_at` - 创建时间

## API 服务

该包提供了 `ExceptionLogService` 类来处理常见的日志操作：

- `logException()` - 记录单个异常
- `batchLogExceptions()` - 批量记录异常
- `cleanOldLogs()` - 清理旧日志
- `getStatistics()` - 获取统计信息
- `getRecentLogs()` - 获取最近日志
- `searchLogs()` - 按条件搜索日志

## 许可证

MIT License