Monolog日志格式自定义实战LineFormatter模板变量全攻略【免费下载链接】monologSends your logs to files, sockets, inboxes, databases and various web services项目地址: https://gitcode.com/gh_mirrors/mo/monolog在 PHP 项目中定制Monolog 日志格式最核心的工具就是 LineFormatter。它通过一套%变量%模板语法让你把日志记录中的时间、级别、通道、上下文等字段自由排列成任意单行文本。这篇教程带你快速掌握 Monolog 日志格式自定义的完整方法从模板变量清单到日期格式、堆栈跟踪等高级开关一文讲透。为什么 LineFormatter 是日志格式化首选Monolog 的每条日志都是一个 LogRecord 对象包含消息、级别、上下文等字段字段说明见 doc/message-structure.md。而 Formatter 负责把这些字段翻译成最终写入文件、Socket 或数据库的字符串。在所有 Formatter 中LineFormatter 最实用它把一条记录格式化为单行字符串特别适合文件日志且支持模板变量插值。它的默认模板定义在源码中一行就能看懂整体结构public const SIMPLE_FORMAT [%datetime%] %channel%.%level_name%: %message% %context% %extra%\n;来源LineFormatter.php#L28三步接入自定义日志格式整个过程只需 3 步建 Formatter → 挂到 Handler → Handler 挂到 Logger。创建LineFormatter实例传入你想要的模板字符串和日期格式创建 Handler如写文件的StreamHandler用setFormatter()把两者绑起来$output %datetime% %level_name% %message% %context% %extra%\n; $dateFormat Y n j, g:i a; $formatter new LineFormatter($output, $dateFormat); $stream new StreamHandler(__DIR__ . /my_app.log, Level::Debug); $stream-setFormatter($formatter); $logger new Logger(security); $logger-pushHandler($stream);完整示例可参考官方文档 doc/01-usage.md#L224-L275。 小技巧同一个 Formatter 可以复用到多个 Handler 上。模板变量完整清单重点看这里模板中所有%xxx%都会被替换为日志记录的真实值。基础变量共 6 个模板变量含义示例输出%datetime%记录时间按日期格式渲染2026-09-17T15:07:1208:00%channel%通道名即new Logger(xxx)里的名字security%level_name%级别名称ERROR%message%日志消息正文支付回调失败%context%上下文数组JSON 序列化{code:500}%extra%处理器写入的附加数据JSON 序列化{ip:127.0.0.1}除了整体输出还支持点号取值单独抽取某个字段模板变量作用%context.foo%只输出 context 中foo键的值%extra.file%只输出 extra 中file键的值例如模板%context.foo% %extra.foo%会输出bar xbar测试用例见 LineFormatterTest.php#L87-L99。⚠️ 注意模板里写了%context.xxx%但记录中没有该键时剩余的%xxx%占位符会被自动清空不会原样输出。自定义日期时间格式LineFormatter继承自 NormalizerFormatter日期格式默认是Y-m-d\TH:i:sPISO 8601 风格含时区定义于 NormalizerFormatter.php#L26。构造函数第二个参数接受任何 PHPDateTime::format支持的格式Y-m-d H:i:s→2026-09-17 15:07:12简洁Y-m-d H:i:s.u→ 带毫秒精度排查性能问题时很有用Y n j, g:i a→2026 9 17, 3:07 pm美式风格5 个进阶开关让日志更好用这些方法都能链式调用覆盖日常 90% 的定制需求1️⃣setMaxLevelNameLength(3)—— 等宽级别名把INFO截断为INF、ERROR截断为ERR多行日志左对齐更整齐。$formatter-setMaxLevelNameLength(3);来源LineFormatter.php#L1212️⃣includeStacktraces()—— 记录异常堆栈默认异常只输出类名消息文件行号开启后会把完整 stack trace 追加到日志里。3️⃣indentStacktraces( )—— 堆栈缩进给堆栈行加缩进让异常块和主日志消息视觉上分开阅读更舒适。4️⃣ignoreEmptyContextAndExtra(true)—— 省略空数组没有 context/extra 时不再输出无意义的[] []日志更干净。5️⃣setBasePath()—— 缩短文件路径设置项目根目录后异常文件路径和堆栈中的公共前缀会被剥掉日志体积明显变小$formatter-setBasePath(__DIR__ . /app);来源LineFormatter.php#L57-L66另外还有allowInlineLineBreaks(true)默认消息中的换行会被压成空格保证一条日志一行打开后允许保留换行。常见问题快答Q模板里的%写错会怎样A不存在的变量占位符会被静默移除不会报错但建议拼写核对。Q为什么我写的%extra.ip%没有输出Aextra是由 Processor如 WebProcessor、UidProcessor填充的没有注册对应处理器时它是空的。处理器列表见 doc/02-handlers-formatters-processors.md。Qcontext 和 extra 有什么区别Acontext是你调用log()时手动传的数据extra由处理器自动写入。详细说明见 doc/message-structure.md。Q要输出 JSON 格式的日志怎么办A换用JsonFormatter本文的单行模板思路依然适用于理解其字段映射。小结你的第一份日志格式配方把上面的技巧组合起来一条生产环境常用配方是$formatter new LineFormatter( [%datetime%] %channel%.%level_name%: %message% %context% %extra%\n, Y-m-d H:i:s ); $formatter-setBasePath(__DIR__) -includeStacktraces() -indentStacktraces( ) -ignoreEmptyContextAndExtra(true);记住核心逻辑LineFormatter 模板字符串 日期格式 若干开关。掌握这张变量清单表后任何自定义日志格式需求都能 5 分钟内搞定。更多 Formatter 与 Handler 的完整对照表请参阅官方文档 doc/02-handlers-formatters-processors.md。【免费下载链接】monologSends your logs to files, sockets, inboxes, databases and various web services项目地址: https://gitcode.com/gh_mirrors/mo/monolog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考