README

此包在 PSR-3 之上实现了我们的一些内部约定。它发布的日志记录器完全兼容 PSR-3，并具有一些额外功能（可选），以及一个使日志记录器创建变得简单的工厂

$factory = new LoggerFactory();
$logger = $factory->create('Active Collab', '1.0.0', 'development', LoggerInterface::LOG_FOR_DEBUG, LoggerInterface::FILE, '/path/to/logs/dir');

一旦设置日志记录器，就可以像使用任何其他 PSR-3 日志记录器一样使用它

$logger->info('Something interesting happened: {what}', [
    'what' => 'really interesting event'
]);

特殊日志记录器包括

1. 使用 LoggerInterface::event() 方法进行事件日志记录。这将记录一个命名事件在 info 级别，并将事件上下文属性设置为事件名称
2. 使用 LoggerInterface::requestSummary() 方法进行请求摘要日志记录。这将记录一些有趣的请求数据，例如执行时间、总查询和查询计数等

日志记录器

该包实现了以下后端

LoggerInterface::FILE - 将日志记录到日志目录中的文件。创建日志记录器时，需要将日志目录作为第一个参数

$logger = $factory->create('Active Collab', '1.0.0', 'development', LoggerInterface::LOG_FOR_DEBUG, LoggerInterface::FILE, '/path/to/logs/dir', 'my-awesome-logs.txt', 0777);

第二个参数是日志文件名，它是可选的。如果跳过，则系统将使用指定文件夹中的 log.txt 文件进行日志记录。第三个参数是文件权限级别。默认为 0644，如果跳过，则可以指定任何值（八进制表示）

请注意，我们设置了轮换文件日志记录，其中仅保留过去 7 天的日志。

LoggerInterface::GRAYLOG - 使用 GELF 格式化程序将消息发送到 Graylog2 服务器。额外的参数是 Graylog2 服务器的主机和端口。如果它们被跳过，则使用 127.0.0.1

$logger = $factory->create('Active Collab', '1.0.0', 'development', LoggerInterface::LOG_FOR_DEBUG, LoggerInterface::GRAYLOG, 'graylog.company.com', 12201);

LoggerInterface::BLACKHOLE - 消息不会记录在任何地方。

消息缓冲

日志记录器被构建为在设置请求详细信息（使用 setAppRequest() 方法）之前缓冲消息。我们延迟写入日志的原因是能够将请求详细信息添加到所有消息中，这样我们就可以稍后连接这些点

// Set HTTP request from PSR-7 ServerRequestInterface
$logger->setAppRequest(new \ActiveCollab\Logger\AppRequest\HttpRequest($request));

// Set CLI request from arguments
$logger->setAppRequest(new \ActiveCollab\Logger\AppRequest\CliRequest('session ID', $_SERVER['argv']));

如果未设置请求，则除非您自己刷新，否则缓冲区不会刷新，或者注册一个关闭函数

$logger->flushBufferOnShutdown();

应用程序详细信息

此包始终记录应用程序名称、版本和环境。这些参数是必需的，并且在创建新的日志记录器实例时需要提供给 FactoryInterface::create() 方法

$logger = $factory->create('Active Collab', '1.0.0', 'development', LoggerInterface::LOG_FOR_DEBUG, LoggerInterface::FILE, '/path/to/logs/dir');

环境参数作为上下文参数与通过日志记录器实例捕获的所有消息一起发送。用户可以使用 FactoryInterface::setAdditionalEnvArguments() 方法指定额外的环境参数

// Additional environment arguments can be set on factory level, and factory will pass them to all loggers that it produces
$factory->setAdditionalEnvArguments([
    'account_id' => 123,
    'extra_argument' => 'with extra value',
]);

// Or you can specify them on logger level
$logger->setAdditionalEnvArguments([
    'account_id' => 123,
    'extra_argument' => 'with extra value',
]);

异常序列化

当异常作为上下文参数传递时，该包将“分解”它们为相关参数组：消息、文件、行、代码和跟踪。如果可用，还将提取之前的异常

try {
    // Something risky
} catch (ExceptioN $e) {
    $logger->error('An {exception} happened :(', [
        'exception' => $e,
    ]);
}

如果您有特殊的异常，它们收集的信息比消息、代码、文件、行、跟踪和之前的异常更多，您可以注册一个回调来提取这些数据

$logger->addExceptionSerializer(function ($argument_name, $exception, array &$context) {
    if ($exception instanceof \SpecialError) {
        foreach ($exception->getParams() as $k => $v) {
            $context["{$argument_name}_extra_param_{$k}"] = $v;
        }
    }
});

回调获取三个参数

1. $argument_name - 在其中找到异常的上下文参数名称
2. $exception_name - 异常本身
3. $context - 访问结果日志消息上下文参数

与额外的环境变量一样，异常序列化程序可以添加到工厂中，并且工厂将将其传递给它生成的所有日志记录器

$factory->addExceptionSerializer(function ($argument_name, $exception, array &$context) {
    if ($exception instanceof \SpecialError) {
        foreach ($exception->getParams() as $k => $v) {
            $context["{$argument_name}_extra_param_{$k}"] = $v;
        }
    }
});

错误处理

日志记录器配备了可以注册错误和异常处理器并将它们直接记录到日志中的类。快速设置

$handler = new ErrorHandler($logger);
$handler->initialize();

要恢复错误和异常处理，只需调用 restore() 方法即可

$handler->restore();

可以根据不同的错误级别配置处理器执行不同的操作。例如，您可以将它配置为在 PHP 警告上抛出异常，或者完全静音事件

$handler->setHowToHandleError(E_STRICT, ErrorHandlerInterface::SILENCE);
$handler->setHowToHandleError(E_DEPRECATED, ErrorHandlerInterface::LOG_NOTICE);
$handler->setHowToHandleError(E_NOTICE, ErrorHandlerInterface::LOG_ERROR);
$handler->setHowToHandleError(E_USER_ERROR, ErrorHandlerInterface::THROW_EXCEPTION);

默认情况下，异常会被记录并重新抛出。此行为可以被关闭

$handler->setReThrowException(false);