Monolog、Laravel与psr/log：一图看懂PSR-3日志生态体系及最佳集成方案

Monolog、Laravel与psr/log：一图看懂PSR-3日志生态体系及最佳集成方案

【免费下载链接】log项目地址: https://gitcode.com/gh_mirrors/lo/log

在 PHP 开发中，PSR-3 日志接口是 Monolog、Laravel 等框架和工具库共同的底层标准。psr/log 包就是这个标准的官方实现：它本身不是日志库，而是一套"日志通用接口"，让你的代码只依赖标准，而不绑定任何具体实现。本文带你一图看懂 PSR-3 生态体系，并给出最佳集成方案。

📦 psr/log 是什么？一个接口统一整个生态

psr/log 的核心只有一句话：定义"一个合格的日志器必须长什么样"。

核心文件一览（都在 src/ 目录下）：

文件	作用
LoggerInterface.php	核心接口，定义 8 个日志级别方法 + 通用的log()方法
LogLevel.php	8 个日志级别常量（emergency → debug）
AbstractLogger.php	抽象基类，帮实现者省掉样板代码
LoggerTrait.php	Trait 版"快捷方法"，适合无法继承 AbstractLogger 的类
LoggerAwareInterface.php / LoggerAwareTrait.php	让任意对象能"接收"一个日志器（setLogger()）
NullLogger.php	"空日志器"，没有日志配置时的安全兜底
InvalidArgumentException.php	非法日志级别时抛出的异常

一句话总结：psr/log 管"契约"，Monolog 管"干活"，Laravel 管"装配"。

🎚️ PSR-3 的 8 级日志分级体系

PSR-3 把日志严重程度分成 8 个等级（定义见 LogLevel.php），从高到低：

级别	语义	什么时候用
emergency	系统不可用	整站宕机、需立即停机处理
alert	必须马上处理	数据库挂了，该发短信叫醒你
critical	严重错误	应用某个核心组件不可用
error	运行时错误	一般异常，需记录并监控
warning	警告（非错误）	使用了废弃 API、潜在隐患
notice	正常但值得关注	系统进入重要状态
info	一般信息	用户登录、关键业务事件
debug	调试细节	开发阶段的海量跟踪信息

💡 新手常见误区：把所有东西都打error。分级后，生产环境开error级别就能过滤噪音，调试时开到debug又不会丢信息。

🏗️ 一图看懂：PSR-3 日志生态体系

┌────────────────────────────────────────────┐ │ 你的业务代码 / 工具库 │ │ 只依赖 LoggerInterface（PSR-3 接口） │ └───────────────────┬────────────────────────┘ │ 类型提示（依赖抽象） ▼ ┌────────────────────────────────────────────┐ │ psr/log（本仓库，PSR-3 标准） │ │ LoggerInterface / LogLevel / NullLogger │ └───────┬───────────────────────┬────────────┘ │ 实现接口 │ 实现接口 ▼ ▼ ┌──────────────────────┐ ┌──────────────────────┐ │ Monolog │ │ Laravel 日志门面 │ │ 写文件/邮件/Slack/ │ │ 底层同样基于 │ │ 数据库等多种 Handler │ │ Monolog 实现 │ └──────────────────────┘ └──────────────────────┘ │ │ └───────────┬───────────┘ ▼ 文件 / 控制台 / 数据库 / 第三方服务

三层关系很清晰：

1. 标准层（psr/log）：本仓库，纯接口 + 少量工具类，零依赖（仅需 PHP 8.0+，见 composer.json）；
2. 实现层（Monolog 等）：真正"写日志"的库，实现LoggerInterface；
3. 应用层（Laravel 等）：在框架中装配日志器，Laravel 的Log门面底层用的正是 Monolog，而 Monolog 遵循的又是 PSR-3。

这就是为什么"给 Laravel 项目换一个日志通道"和"给自研库加日志"用的是同一套 API。

🚀 三步完成集成：从安装到调用

第 1 步：安装标准包

composer require psr/log

第 2 步：通过构造函数注入日志器（官方推荐写法，见 README.md）：

class Foo { public function __construct(private LoggerInterface $logger) {} public function doSomething() { $this->logger->info('正在处理订单', ['order_id' => 42]); try { // ... } catch (\Exception $e) { $this->logger->error('处理失败', ['exception' => $e]); } } }

第 3 步：运行时装入具体实现

// 生产：Monolog（文件 + 邮件告警） $foo = new Foo(new \Monolog\Logger('app')); // 没有日志配置时：用 NullLogger 兜底，避免 if 判断满天飞 $foo = new Foo(new NullLogger());

消息支持{placeholder}占位符（如'用户 {name} 登录'，配合['name' => 'Tom']），异常统一放在 context 的exception键中（规范见 LoggerInterface.php 注释）。

✅ 最佳实践清单

• 依赖接口，不依赖实现：构造函数写LoggerInterface，测试时可以轻松换成内存桩，替换 Monolog 也不改业务代码；
• 用 NullLogger.php 做默认值：官方注释明确建议——与其到处写if ($this->logger)，不如默认注入NullLogger；
• 自己写日志器时别手搓 8 个方法：继承 AbstractLogger.php 或引入 LoggerTrait.php（8 个级别方法已帮你写好，只需实现一个log()）；
• 让对象"可接受"日志器：实现 LoggerAwareInterface.php 或引入LoggerAwareTrait，调用方随时setLogger()挂载日志能力；
• 级别宁缺毋滥：warning不是error的垃圾桶，debug别上生产。

📌 总结

问题	答案
psr/log 能直接记录日志吗？	不能，它只是接口标准
Monolog 扮演什么角色？	实现者，提供 Handler 体系真正落地日志
Laravel 怎么融入？	底层用 Monolog，门面统一暴露 PSR-3 兼容 API
新手怎么选？	应用项目直接用框架日志；自研库依赖psr/log接口，实现交给使用方

掌握 PSR-3，你就掌握了 PHP 日志生态的"通用插座"——写一次接口依赖，Monolog、Laravel 乃至任何实现都能即插即用。

【免费下载链接】log项目地址: https://gitcode.com/gh_mirrors/lo/log