PHPackages                             felo-z/laravel-sql-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. [Database & ORM](/categories/database)
4. /
5. felo-z/laravel-sql-logger

ActiveLibrary[Database & ORM](/categories/database)

felo-z/laravel-sql-logger
=========================

Log SQL queries in Laravel/Lumen framework

v2.3.01(3mo ago)138MITPHP

Since Sep 22Pushed 3mo agoCompare

[ Source](https://github.com/Felo-Z/laravel-sql-logger)[ Packagist](https://packagist.org/packages/felo-z/laravel-sql-logger)[ RSS](/packages/felo-z-laravel-sql-logger/feed)WikiDiscussions master Synced today

READMEChangelog (2)Dependencies (18)Versions (4)Used By (0)

Laravel SQL Logger 开发文档
=======================

[](#laravel-sql-logger-开发文档)

项目概述
----

[](#项目概述)

Laravel SQL Logger 是一个用于 Laravel/Lumen 框架的 SQL 查询日志记录工具。该工具可以记录所有 SQL 查询和慢查询到日志文件中，帮助开发者在开发过程中验证查询是否有效，并确保应用程序不会运行过多或过慢的数据库查询。

功能特点
----

[](#功能特点)

- 记录所有 SQL 查询到日志文件
- 记录慢查询到单独的日志文件
- 可配置的查询格式化
- 可配置的日志文件命名和存储位置
- 支持 Laravel 和 Lumen 框架
- 支持命令行（Artisan）和 HTTP 请求的查询日志区分
- 可通过环境变量轻松配置

系统架构
----

[](#系统架构)

Laravel SQL Logger 通过监听 Laravel 的数据库查询事件来捕获 SQL 查询，然后根据配置将查询记录到指定的日志文件中。

### 核心组件

[](#核心组件)

1. **ServiceProvider**: 负责注册服务和监听数据库查询事件
2. **SqlLogger**: 主要日志记录器，处理查询日志的入口点
3. **Query**: 创建 SqlQuery 对象
4. **SqlQuery**: 表示单个 SQL 查询的对象
5. **Writer**: 负责将查询写入日志文件
6. **Formatter**: 格式化 SQL 查询以便记录
7. **Config**: 处理配置选项
8. **FileName**: 生成日志文件名

调用流程图
-----

[](#调用流程图)

 ```
sequenceDiagram
    participant App as Laravel 应用
    participant Provider as ServiceProvider
    participant Logger as SqlLogger
    participant Query as Query
    participant SqlQuery as SqlQuery
    participant Writer as Writer
    participant Formatter as Formatter
    participant Config as Config
    participant FileName as FileName

    App->>Provider: 启动应用
    Provider->>Provider: register()
    Provider->>Config: 加载配置
    Provider->>Logger: 创建 SqlLogger 实例
    Provider->>App: 监听数据库查询事件

    App->>Provider: 执行数据库查询
    Provider->>Logger: log(query, bindings, time)
    Logger->>Query: get(number, query, bindings, time)
    Query->>SqlQuery: 创建 SqlQuery 实例
    SqlQuery-->>Logger: 返回 SqlQuery 对象
    Logger->>Writer: save(sqlQuery)

    Writer->>Config: 检查配置
    Writer->>Formatter: getLine(sqlQuery)
    Formatter->>Formatter: 格式化查询
    Formatter-->>Writer: 返回格式化的查询字符串

    alt 记录所有查询
        Writer->>FileName: getForAllQueries()
        FileName-->>Writer: 返回文件名
        Writer->>Writer: saveLine(line, fileName)
    end

    alt 记录慢查询
        Writer->>Config: 检查是否为慢查询
        Writer->>FileName: getForSlowQueries()
        FileName-->>Writer: 返回文件名
        Writer->>Writer: saveLine(line, fileName)
    end
```

      Loading 关键类和函数
------

[](#关键类和函数)

### 1. ServiceProvider

[](#1-serviceprovider)

**路径**: `src/Providers/ServiceProvider.php`

**主要职责**:

- 注册服务
- 合并配置
- 监听数据库查询事件

**关键函数**:

- `register()`: 注册服务和监听器
- `shouldLogAnything()`: 检查是否应该记录任何查询
- `getListenClosure()`: 获取用于监听数据库查询的闭包函数

### 2. SqlLogger

[](#2-sqllogger)

**路径**: `src/SqlLogger.php`

**主要职责**:

- 处理查询日志的入口点
- 记录 SQL 查询

**关键函数**:

- `log(query, bindings, time)`: 记录 SQL 查询

### 3. Query

[](#3-query)

**路径**: `src/Query.php`

**主要职责**:

- 创建 SqlQuery 对象

**关键函数**:

- `get(number, query, bindings, time)`: 创建并返回 SqlQuery 对象

### 4. SqlQuery

[](#4-sqlquery)

**路径**: `src/Objects/SqlQuery.php`

**主要职责**:

- 表示单个 SQL 查询
- 存储查询相关信息

**关键函数**:

- `get()`: 获取完整的查询（带绑定值）
- `raw()`: 获取原始 SQL（不带绑定值）
- `time()`: 获取查询执行时间
- `number()`: 获取查询编号
- `bindings()`: 获取查询绑定值

### 5. Writer

[](#5-writer)

**路径**: `src/Writer.php`

**主要职责**:

- 将查询写入日志文件

**关键函数**:

- `save(sqlQuery)`: 保存查询到日志文件
- `shouldLogQuery(query)`: 检查是否应该记录查询
- `shouldLogSlowQuery(query)`: 检查是否应该记录慢查询
- `saveLine(line, fileName, override)`: 保存一行到日志文件

### 6. Formatter

[](#6-formatter)

**路径**: `src/Formatter.php`

**主要职责**:

- 格式化 SQL 查询以便记录

**关键函数**:

- `getLine(sqlQuery)`: 获取格式化的行
- `queryLine(query)`: 获取查询行
- `originLine()`: 获取来源行（请求或命令行）
- `time(time)`: 格式化时间

### 7. Config

[](#7-config)

**路径**: `src/Config.php`

**主要职责**:

- 处理配置选项

**关键函数**:

- `logDirectory()`: 获取日志目录
- `logAllQueries()`: 是否记录所有查询
- `logSlowQueries()`: 是否记录慢查询
- `slowLogTime()`: 获取慢查询时间阈值
- `entryFormat()`: 获取条目格式

### 8. FileName

[](#8-filename)

**路径**: `src/FileName.php`

**主要职责**:

- 生成日志文件名

**关键函数**:

- `getForAllQueries()`: 获取所有查询的文件名
- `getForSlowQueries()`: 获取慢查询的文件名
- `createFileName(fileName)`: 创建文件名
- `parseFileName(fileName)`: 解析文件名（包含日期）

配置选项
----

[](#配置选项)

配置文件位于 `publish/config/sql_logger.php`，主要配置选项包括：

### 一般配置

[](#一般配置)

- `directory`: 日志文件保存目录
- `use_seconds`: 是否以秒为单位显示执行时间
- `console_log_suffix`: Artisan 查询日志后缀
- `extension`: 日志文件扩展名

### 格式化配置

[](#格式化配置)

- `new_lines_to_spaces`: 是否将换行符替换为空格
- `entry_format`: 单个条目格式

### 所有查询配置

[](#所有查询配置)

- `enabled`: 是否记录所有 SQL 查询
- `override_log`: 是否覆盖日志文件
- `pattern`: 匹配查询的模式
- `file_name`: 日志文件名（不含扩展名）

### 慢查询配置

[](#慢查询配置)

- `enabled`: 是否记录慢 SQL 查询
- `min_exec_time`: 慢查询的最小执行时间（毫秒）
- `pattern`: 匹配慢查询的模式
- `file_name`: 慢查询日志文件名（不含扩展名）

使用方法
----

[](#使用方法)

### 安装

[](#安装)

1. 通过 Composer 安装：

    ```
    composer require mnabialek/laravel-sql-logger --dev
    ```
2. 对于 Laravel < 5.5，在 `config/app.php` 中添加服务提供者：

    ```
    Mnabialek\LaravelSqlLogger\Providers\ServiceProvider::class,
    ```
3. 对于 Lumen，在 `bootstrap/app.php` 中添加：

    ```
    $app->register(Mnabialek\LaravelSqlLogger\Providers\ServiceProvider::class);
    ```
4. 发布配置文件：

    ```
    php artisan vendor:publish --provider="Mnabialek\LaravelSqlLogger\Providers\ServiceProvider"
    ```
5. 在 `.env` 文件中添加配置项：

    ```
    SQL_LOGGER_DIRECTORY="logs/sql"
    SQL_LOGGER_USE_SECONDS=false
    SQL_LOGGER_CONSOLE_SUFFIX=
    SQL_LOGGER_LOG_EXTENSION=".sql"
    SQL_LOGGER_ALL_QUERIES_ENABLED=true
    SQL_LOGGER_ALL_QUERIES_OVERRIDE=false
    SQL_LOGGER_ALL_QUERIES_PATTERN="#.*#i"
    SQL_LOGGER_ALL_QUERIES_FILE_NAME="[Y-m-d]-log"
    SQL_LOGGER_SLOW_QUERIES_ENABLED=true
    SQL_LOGGER_SLOW_QUERIES_MIN_EXEC_TIME=100
    SQL_LOGGER_SLOW_QUERIES_PATTERN="#.*#i"
    SQL_LOGGER_SLOW_QUERIES_FILE_NAME="[Y-m-d]-slow-log"
    SQL_LOGGER_FORMAT_NEW_LINES_TO_SPACES=false
    SQL_LOGGER_FORMAT_ENTRY_FORMAT="/* [origin]\\n   Query [query_nr] - [datetime] [[query_time]] */\\n[query]\\n[separator]\\n"

    ```

### 日志格式

[](#日志格式)

默认情况下，日志条目的格式如下：

```
/* Origin (request): GET http://example.com/api/users
   Query 1 - 2023-09-22 10:00:00 [15ms] */
SELECT * FROM users WHERE id = 1;
/*==================================================*/

```

可以通过修改 `SQL_LOGGER_FORMAT_ENTRY_FORMAT` 环境变量来自定义格式。

最佳实践
----

[](#最佳实践)

1. **仅在开发环境中使用**：在生产环境中禁用此包，以避免影响应用程序性能。
2. **监控慢查询**：定期检查慢查询日志，优化性能较差的查询。
3. **合理设置慢查询阈值**：根据应用程序的性能要求，设置合适的慢查询时间阈值。
4. **使用模式过滤**：使用 `pattern` 配置选项过滤特定类型的查询。

扩展和定制
-----

[](#扩展和定制)

如果需要扩展或定制 Laravel SQL Logger，可以考虑以下方法：

1. **自定义格式化器**：继承 `Formatter` 类并重写 `getLine` 方法。
2. **自定义写入器**：继承 `Writer` 类并重写 `save` 方法。
3. **添加更多日志目标**：修改 `Writer` 类，添加对其他日志目标的支持，如数据库或远程服务。

故障排除
----

[](#故障排除)

1. **日志文件未创建**：

    - 检查日志目录是否存在且具有正确的权限
    - 确保已正确配置环境变量
2. **未记录查询**：

    - 确保 `SQL_LOGGER_ALL_QUERIES_ENABLED` 设置为 `true`
    - 检查 `SQL_LOGGER_ALL_QUERIES_PATTERN` 是否匹配您的查询
3. **未记录慢查询**：

    - 确保 `SQL_LOGGER_SLOW_QUERIES_ENABLED` 设置为 `true`
    - 检查 `SQL_LOGGER_SLOW_QUERIES_MIN_EXEC_TIME` 是否设置得太高

结论
--

[](#结论)

Laravel SQL Logger 是一个强大而灵活的工具，可以帮助开发者监控和优化数据库查询。通过记录所有查询和慢查询，它提供了宝贵的见解，帮助识别和解决性能问题。

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance80

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 99.1% 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

Every ~91 days

Total

3

Last Release

104d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6071340?v=4)[zhangfei](/maintainers/Felo-Z)[@Felo-Z](https://github.com/Felo-Z)

---

Top Contributors

[![mnabialek](https://avatars.githubusercontent.com/u/7656807?v=4)](https://github.com/mnabialek "mnabialek (110 commits)")[![yhbyun](https://avatars.githubusercontent.com/u/946080?v=4)](https://github.com/yhbyun "yhbyun (1 commits)")

---

Tags

loglaravellumensqlloggersql logsql loggerlog sql querieslog sql

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/felo-z-laravel-sql-logger/health.svg)

```
[![Health](https://phpackages.com/badges/felo-z-laravel-sql-logger/health.svg)](https://phpackages.com/packages/felo-z-laravel-sql-logger)
```

###  Alternatives

[mnabialek/laravel-sql-logger

Log SQL queries in Laravel/Lumen framework

162820.6k2](/packages/mnabialek-laravel-sql-logger)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M201](/packages/laravel-ai)[illuminate/database

The Illuminate Database package.

2.8k54.9M11.7k](/packages/illuminate-database)[onlime/laravel-sql-reporter

Log SQL queries in Laravel framework

111.5k](/packages/onlime-laravel-sql-reporter)[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k9.0M69](/packages/spatie-laravel-responsecache)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)

PHPackages © 2026

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