搜索pls / log
PLS 记录器规范
Requires
- php: ^7.3
This package is not auto-updated.
Last update: 2024-09-15 04:05:33 UTC
README
本包描述了一个日志库的通用接口。其目标是允许库接收一个实现了 Pls\Log\Logger 的对象，并以简单通用的方式向其写入日志。
本文件中“必须”，“禁止”，“必需”，“应该”，“不应该”，“推荐”，“可能”，“可选”等关键词的解释，应参照 RFC 2119 的描述。
1. 规范
实现必须完全实现指定的功能，并且可以提供比指定更多的功能。
Pls\Log\LoggerInterface 暴露了一个名为 log 的方法，用于记录消息。该方法接受三个参数：$level、$message 和 $context（可选）。
1.1 $level
这是一个 int 类型的值，对应于八个 RFC 5424 严重性级别之一。
一个名为 LogLevel 的接口提供了与 int 严重性级别映射的语义标签的常量。建议用户将这些常量作为 $level 值传递。
传递一个本规范未定义的 $level 值（即不大于等于 0 且小于等于 7），必须抛出 Pls\Log\InvalidSeverity 的一个实例。
1.2 $message
这是一个用户定义的 string 值，用于记录。
消息可以包含占位符，实现者可以将这些占位符替换为上下文数组中的值。
占位符名称必须与上下文数组中的键相对应。
占位符名称必须由一个单开大括号 { 和一个单闭大括号 } 分隔。分隔符和占位符名称之间不得有空白字符。
占位符名称只能由字符 A-Z、a-z、0-9、下划线 _ 和点 . 组成。
实现者可以使用占位符来实现各种转义策略，并将日志转换为显示格式。用户不应预先转义占位符值，因为它们无法确定数据将在何种上下文中显示。
传递包含格式错误的占位符名称的 $message 值，必须抛出 Pls\Log\InvalidMessage 的一个实例。
1.3 $context
这是一个可选的用户定义的 array；默认值为空数组 []。它旨在包含不适合在字符串中很好地表示的任何额外信息。数组可以包含任何内容。上下文中的给定值不得抛出异常或引发任何 PHP 错误、警告或通知。
数组的键和值可以是 PHP 允许的任何类型，并且可以在 $context 数组中具有不同的类型，但与占位符名称对应的数组键必须是 string 类型，与 $message 中的占位符名称相同。
必须为 $message 中的每个占位符名称提供一个数组值。传递一个不包含与 $message 中存在的占位符名称对应的键的 $context 数组，必须抛出 Pls\Log\InvalidContext 的一个实例。
如果将实现 \Throwable 的对象传递到上下文数据中，它必须在 'thrown' 键中。记录异常是一种常见的模式，这允许实现者当日志后端支持时从异常中提取堆栈跟踪。实现者在使用之前必须仍然验证 'thrown' 键实际上是 \Thowable，因为它可能包含任何内容。
1.4 异常
所有实现抛出的异常都必须实现 Pls\Log\LoggerException。
2. 包
这些接口作为 pls/log 包的一部分提供。
提供 pls/log 实现的包应声明它们提供 pls/log-implementation 1.0.0。
需要实现的项目应要求 pls/log-implementation ^1.0.0。
3. 安装
使用 composer 安装
composer require pls/log
需要 PHP >= 7.3。
4. 许可证
此包根据 MIT 许可证 发布。