README

概览

此包提供全局日志函数，并从所有PSR-3实现中解耦。而不是在每个需要日志功能的地方存储或注入PSR-3日志接口，日志存储在全局单例对象中，可以在启动/引导时全局配置。

全局函数可以通过任何函数或类成员（包括静态类成员）调用。如果配置了，则使用全局配置的日志记录器，否则使用原生的php error_log() 函数。

有关PSR-3的更多信息，请参阅https://www.php-fig.org/psr/psr-3/

安装

composer require sterlingdesign/global-logging

安装包含测试文件，以便您可以验证安装并尝试操作和配置。脚本应在命令行中运行，例如

php -f vendor/sterlingdesign/global-logging/test/test-global-logging-cli.php

日志目标配置

在简单情况下，日志函数（见下文“全局函数”）可以不配置任何PSR-3日志目标使用。如果没有配置PSR-3日志记录器，则使用内置的PHP函数 error_log($message, 0) 将消息发送到PHP的系统日志记录器（见https://php.ac.cn/manual/en/function.error-log）。

注意：除非配置了另一个PSR-3日志记录器（见下文），否则所有LogXXXX调用都仅发送到php系统日志。如果你的应用程序需要电子邮件或短信通知关键错误，请配置具有该功能的许多日志记录器之一，例如monolog。

如果你的应用程序使用PSR-3兼容的日志记录设施，如'monolog'，你可以创建该日志记录器的实例并将该对象设置为全局目标。如果已配置PSR-3日志记录器，则所有LogXXXX函数使用该日志记录器，而不是原生的PHP error_log() 函数。

your_bootstrap_file.php

<?php

use Sterling\LogTarget;
use Psr\Log\LogLevel;

if(class_exists('\\Monolog\\Logger') && class_exists('\\Monolog\\Handler\\StreamHandler'))
    {
    // If Using a PSR-3 Logger, configure it and tell LogTarget to use it:
    $log = new \Monolog\Logger('name');
    $log->pushHandler(new \Monolog\Handler\StreamHandler(__DIR__ . '/testing_monolog.log', Logger::WARNING));
    LogTarget::getInstance()->setLogger($log);
    }
else
    {
    // The following option only applies if you are not using a logger:  
    // If you don't have a way to send debug logs back to the client, 
    // you may want to write all LogXXXX calls to the PHP system log.
    // CAUTION: This could potentially result in large amounts of log data
    LogTarget::getInstance()->setIgnoreLogLevels([]);
    // Or, maybe you would like to ignore all log calls below Warning
    // to reduce the amount of data written to the PHP system log:
    LogTarget::getInstance()->setIgnoreLogLevels([LogLevel::NOTICE, LogLevel::INFO, LogLevel::DEBUG]);
    }

// - Configure other LogTarget Options:    
// enable automatic context generation for all LogLevels for more detail:
LogTarget::getInstance()->setAutomaticContextGenerationLevels(LogTarget::ALL_LEVELS);
// disable storing log calls in memory if you don't need to look at them or your PSR-3 logger already does this
LogTarget::getInstance()->setStoreInMemory(false);

some_application_file.php

// add records to the log: These functions are supplied by this package:
LogWarning('Foo');
LogError('Bar');
LogDebug("Testing!");

有关工作示例，请参阅包含的测试脚本，应安装于vendor\sterlingdesign\global-logging\test\test-global-logging-cli.php

全局函数

这些函数由本包提供，并由自动加载器加载到顶级全局命名空间。

LogEmergency(mixed $item, array $context = array());

LogAlert(mixed $item, array $context = array());

LogCritical(mixed $item, array $context = array());

LogError(mixed $item, array $context = array());

LogWarning(mixed $item, array $context = array());

LogNotice(mixed $item, array $context = array());

LogInfo(mixed $item, array $context = array());

LogDebug(mixed $item, array $context = array());

LogAtLevel($level, mixed $item, array $context = array());

// For LogAtLevel, the $level parameter should be one of the \Psr\Log\LogLevel constants.
// If it is not one of the defined values, logging will default 
// to \Psr\Log\LogLevel::ERROR

全局函数是调用全局单例 \Sterling\LogTarget 上的 LogAtLevel 函数的简单包装。也可以直接使用 LogTarget，例如

\Sterling\LogTarget::getInstance()->LogAtLevel(\Psr\Log\LogLevel::DEBUG, "Testing!", []);

附加功能

内存中日志存储

除了将 LogXXXX 函数调用转发到PSR-3日志记录器（如果已配置）或PHP日志（如果没有配置PSR-3日志记录器）之外，LogTarget 类还将在内存数组中存储当前请求的 Log 调用信息。这在调试时将当前请求日志信息回显到客户端很有用。

默认情况下，对当前请求的 LogXXXX 函数的每个调用都存储在一个数组数组中。例如，要获取存储的 Log 调用的数组，可以执行以下操作

require_once "path/to/your/autoload.php";
// Optionally configure any Psr\Log\LoggerInterface you are using
// \Sterling\LogTarget::getInstance()->setLogger($oMyLogger);

LogDebug("Testing!");
echo \Sterling\LogTarget::getInstance()->getLogFormatted();

如果您的某个日志处理器已经具有此功能，您可以通过调用禁用 Sterling\LogTarget 的内存存储

\Sterling\LogTarget::getInstance()->setStoreInMemory(false);

或者您可能希望根据您是否在调试来动态禁用/启用 Log 调用的内存存储

\Sterling\LogTarget::getInstance()->setStoreInMemory(IsDebug());

自动上下文生成

PSR-3标准提供向Logger::log函数提供上下文。如果没有明确提供给LogXXXX函数，则可以自动生成这些上下文，形式为debug_backtrace。

您可以使用LogTarget::setAutomaticContextGenerationLevels()函数控制是否自动生成哪些LogLevel级别的回溯信息。参数应该是一个数组，指定哪些LogLevel应该自动生成上下文。要禁用自动上下文生成，请传递一个空数组。

路线图

当前实现提供了基本的PHP日志文件输出，无需进一步工作。未来，根据需求，可能添加格式化功能，以便在没有PSR-3 Logger对象的情况下，可以自定义PHP日志文件输出。

当前目标是纠正现有实现中的明显错误，然后维护该包以与PSR-3标准兼容，并与其原生PHP函数error_log兼容。

如果有人提出好主意，可能会引入破坏性变更，并在未来的主要版本发布中引入。

欢迎贡献。

sterlingdesign / global-logging

维护者

详情