README

目录

• 关于
• 配置
• 绑定点
• 记录
• 安装
• 单元测试
• 参考指南
• 规格
  • 日志行是如何格式化的
  • 如何绑定自定义记录器

关于

此API是一个基于简单性和灵活性原则的（需要开发人员绑定的）基本记录系统。与当今行业标准Monolog相比，它不会带来任何实际的性能损失，并且具有几乎为零的学习曲线，只需将复杂性保持在最低同时提供扩展功能的能力。

记录的整体思想简化为仅仅三个步骤

• 配置：设置一个XML文件，其中为每个开发环境设置一个或多个记录器
• 绑定点：将XML/代码中定义的用户定义组件绑定到API原型，以获得必要的功能
• 记录：创建一个基于上述XML的Wrapper实例，并使用它进行记录

API完全遵循PSR-4规范，仅需要PHP8.1+解释器和SimpleXML扩展。要快速了解它是如何工作的，请查看

• 安装：描述如何在您的计算机上安装API，上述步骤
• 单元测试：API具有100%单元测试覆盖率，使用UnitTest API而不是PHPUnit以获得更大的灵活性
• 示例：展示了基于单元测试的API功能的深入示例，基于Wrapper

内部所有类都属于 Lucinda\Logging 命名空间！

配置

要配置此API，您必须有一个包含 loggers 标签的XML文件

<loggers path="...">
	<{ENVIRONMENT}>
		<logger class="..." {OPTIONS}/>
		...
	</{ENVIRONMENT}>
	...
</loggers>

在哪里

• loggers： (必填)包含全局记录策略。
  • {ENVIRONMENT}：开发环境名称（将被替换为“local”，“dev”，“live”等）
    • logger：存储单个记录器的配置设置（例如：文件记录器）
      • class： (必填) AbstractLoggerWrapper 实现的完整类名，封装相应的记录器配置。可用值
        • Lucinda\Logging\Driver\File\Wrapper：如果您想将记录到文件，请使用此选项
        • Lucinda\Logging\Driver\SysLog\Wrapper：如果您想将记录到syslog，请使用此选项
        • 任何用户自定义的PSR-4兼容PHP类（包括命名空间）实例，用于您的自定义日志记录器（见：如何绑定新的日志记录器）
      • {选项}：配置上述class标识的相应日志记录器所需的额外属性列表
        • application：（如果使用Driver\SysLog\Wrapper）标识您的网站与其他syslog行的值。例如：“mySite”
        • format：（如果使用Driver\SysLog\Wrapper或Driver\File\Wrapper）控制日志行中显示的内容（见：如何格式化日志行）。例如：“%d %v %e %f %l %m %u %i %a”
        • path：（如果使用Driver\File\Wrapper）保存日志的文件的基名。例如：“messages”
        • rotation：（如果使用Driver\File\Wrapper）用于旋转日志的日期算法。例如：“Y-m-d”
        • 其他：如果使用自定义日志记录器。它们的值可以通过setLogger方法的参数获取。CLASS需要实现。（见：如何绑定新的日志记录器）

示例

<loggers>
    <local>
        <logger class="Lucinda\Logging\Driver\File\Wrapper" path="messages" format="%d %v %e %f %l %m %u %i %a" rotation="Y-m-d"/>
    </local>
    <live>
        <logger class="Lucinda\Logging\Driver\File\Wrapper" path="messages" format="%d %v %e %f %l %m %u %i %a" rotation="Y-m-d"/>
        <logger class="Lucinda\Logging\Driver\SysLog\Wrapper" application="unittest" format="%v %e %f %l %m %u %i %a"/>
    </live>
</loggers>

绑定点

为了保持灵活性和达到最高性能，API只假设那些绝对必要的！它反而为开发者提供了一种通过XML绑定到其原型的能力

API已经内置了以下AbstractLoggerWrapper实现

• Lucinda\Logging\Driver\File\Wrapper：用于在磁盘上的旋转文件中记录日志
• Lucinda\Logging\Driver\SysLog\Wrapper：用于syslog记录

但是，开发者可以绑定自己的（请参阅：如何绑定自定义日志记录器）

记录

现在XML配置完成后，您可以通过查询Wrapper来获取日志记录器，以便在需要时保存和使用

$object = new Lucinda\Logging\Wrapper(simplexml_load_file(XML_FILE_NAME), DEVELOPMENT_ENVIRONMENT);
$logger = $object->getLogger();

返回的日志记录器是一个Logger，它通过一个以日志操作为中心的通用接口隐藏了下面的日志记录器（或多个）的复杂性。每个Logger必须有一个AbstractLoggerWrapper，其任务是根据XML中的信息生成它。

注意：因为XML解析有一些成本，建议将$logger保存到某处并在整个应用程序生命周期中重复使用它。

安装

首先选择一个API将安装的文件夹，然后使用控制台在该文件夹中写入此命令

composer require lucinda/logging

然后创建一个包含配置设置的configuration.xml文件（见上面的配置）和一个包含以下代码的index.php文件（见上面的记录）在项目根目录中

require(__DIR__."/vendor/autoload.php");
$object = new Lucinda\Logging\Wrapper(simplexml_load_file("configuration.xml"), "local");
$logger = $object->getLogger();
$logger->info("test");

如果使用与上面示例相同的loggers标签，则上述代码已在messages__YYYY-MM-DD.log文件中记录了一条“test”消息，优先级为LOG_INFO。

单元测试

有关测试和示例，请检查API源中的以下文件/文件夹

• test.php：在控制台运行单元测试
• unit-tests.xml：设置单元测试并模拟 "loggers" 标签
• tests：来自 src 文件夹的类的单元测试
• tests_drivers：来自 drivers 文件夹的类的单元测试

注意：首次运行时，test.php 将在 syslog 测试中失败，但从此刻起将一直通过

参考指南

Logger 接口

Logger 接口提供了以下方法的基于级别的日志记录的蓝图

使用示例

https://github.com/aherne/php-logging-api/blob/master/drivers/File/Logger.php

抽象类 LoggerWrapper

AbstractLoggerWrapper 抽象类通过以下公共方法实现了将 XML 中的数据转换为 Logger 实例的转换

以及以下原型方法，该原型方法需要由开发人员实现

使用示例

https://github.com/aherne/php-logging-api/blob/master/drivers/File/Wrapper.php

规格

一些指南帮助开发者充分利用此 API

• 日志行是如何格式化的
• 如何绑定自定义记录器

日志行是如何格式化的

如上所示，logger 标签的 class 属性为 Driver\File\Wrapper 和 Driver\SysLog\Wrapper 支持一个 format 属性，其值可以是以下内容的拼接

• %d：当前日期，使用 Y-m-d H:i:s 格式。
• %v：与调用的 Logger 方法匹配的 syslog 优先级常量值。
• %e：抛出的异常类的名称 ()
• %f：记录消息或抛出 Throwable 的文件的绝对位置
• %l：消息记录或 Throwable/Exception 被抛出的文件中上面的行
• %m：记录的消息或 Throwable 消息的值
• %e：如果日志来源是 Throwable，则 Throwable 的类名
• %u：记录发生时 URL 的值，如果可用（$_SERVER["REQUEST_URI"] 的值）
• %a：记录发生时 USER AGENT 头的值，如果可用（$_SERVER["HTTP_USER_AGENT"] 的值）
• %i：记录发生时 IP 的值，如果可用（$_SERVER["REMOTE_ADDR"] 的值）

示例

<logger format="%d %f %l" .../>

如何绑定自定义的 logger

假设您想要将新的 SQL logger 绑定到此 API。首先，您需要实现 logger 本身，它必须扩展 Logger 并实现其所需的 log 方法

class SQLLogger extends Lucinda\Logging\Logger
{
    private $schema;
    private $table;

    public function __construct(string $schema, string $table)
    {
        $this->schema = $schema;
        $this->table = $table;
    }

    protected function log($info, int $level): void
    {
        // log in sql database based on schema, table, info and level
    }
}

现在，您需要将上面的 logger 绑定到 XML 配置。为此，您必须创建另一个扩展 AbstractLoggerWrapper 的类并实现其所需的 setLogger 方法

class SQLLoggerWrapper extends Lucinda\Logging\AbstractLoggerWrapper
{
    protected function setLogger(\SimpleXMLElement $xml): Lucinda\Logging\Logger
    {
        $schema = (string) $xml["schema"];
        $table = (string) $xml["table;
        return new SQLLogger($schema, $table);
    }
}

在这种情况下，如果 composer.json 中的 "psr-4" 属性将 "Lucinda\Project" 与 "src/" 文件夹关联，那么 SQLLoggerWrapper 必须放在 src/Loggers 文件夹中，然后您最终需要将其绑定到 XML

<loggers>
    <local>
        <logger class="Lucinda\Project\Loggers\SQLLoggerWrapper" table="logs" schema="logging_local"/>
    </local>
    <live>
        <logger class="Lucinda\Project\Loggers\SQLLoggerWrapper" table="logs" schema="logging_production"/>
    </live>
</loggers>