README

符合PSR-3规范的日志实现，方便全局日志记录。

该包提供两个关键类

Northrook\Logger();     // a PSR-3 compliant logger.
Northrook\Logger\Log(); // a static accessor to any PSR-3 compliant logger.

本包的目的是提供跨PHP应用的简单日志记录，尤其是在依赖注入可能繁琐或不切实际的情况下。

使用静态Log类，您可以轻松地将日志记录到LoggerInterface实例。

将其视为对LoggerInterface实例的外观或代理。

如果您是面向对象的严格主义者，可以直接使用Logger类。

安装

使用composer安装最新版本

composer require northrook/logger

基本用法

Log类是对一组LoggerInterface的静态访问器。

use Northrook\Logger\Log;

Log::info( 'Hello World!' );

当调用任何Log方法时，如果尚未实例化，则记录器将实例化一个新的Logger对象。

包含的Logger将是默认值。

分配记录器

您可以使用Log::setLogger()手动分配LoggerInterface

use Northrook\Logger\Log;

Log::setLogger( 
    logger: new Logger(), // LoggerInterface
    import: true,         // bool - default: true
);

如果setLogger提供了一个Northrook\Logger实例，它将导入任何先前的LoggerInterface中的日志条目。

如果您只想覆盖当前的LoggerInterface而不导入，则将第二个参数传递为false

Log::setLogger( 
    logger: new Logger(), 
    import: false, 
);

这在您需要在代码的早期部分实例化任意的LoggerInterface，然后在稍后使用包含的Northrook\Logger类时很有用。

Log将充当对LoggerInterface实例的代理，使用包含的Northrook\Logger类根本不是必需的。

日志 - 静态访问器

它提供了所有PSR-3方法，还有一些额外的方法。

任意的log()被替换为Log::entry()方法。

记录异常

Log类提供了一个轻松记录异常的方法

use Northrook\Logger\Log;

try {
    $variable = \file_get_contents( 'data.json' );
} catch( \Exception $exception ) {
    Log::exception( 
        $exception,   // required
        level: null,  // optional
        message: null // optional
        context: [],  // optional
     );
}

// logged as:
0 => 'warning',
1 => 'ile_get_contents(data.json): Failed to open stream: No such file or directory',
2 => [ 'exception' => $exception ],

它将解析异常并相应地记录。

如果提供了，则不会覆盖$level或$message。

$context['exception']将被设置为提供的$$exception。

精确时间戳

在设置使用Log::setLogger()的LoggerInterfacing时，您可以传递一个bool $precision参数，设置静态$enablePrecision属性。

重要

默认值是true。建议根据您的环境设置此值，因为它在生产环境中可能很昂贵。

当首次调用Log::setLogger()时，将分配一个静态整数到hrtime(true)。这用于计算DeltaMs和OffsetMs值。

Log::entry()的每个条目都有一个?bool $precision参数，默认为null，使用静态$enablePrecision属性。

使用此参数设置当前Log::entry()调用的$precision。

use Northrook\Logger\Log;

Log::setLogger( 
    logger: new Logger(), 
    import: true, 
    precision: true, // default: true
);

// enable precision for the current entry
Log::entry( 'Hello World!', precision: true );

// disable precision for the current entry
Log::entry( 'Hello World!', precision: false );

带有$precision记录的条目将在$context数组中添加以下键

'precision' => [
    "hrTime" => 330531205286100 // The hrtime at the time of the log entry
    "hrDelta" => 1081000        // The difference the current entry and first `Log::entry()` call
    "DeltaMs" => "1.08ms"       // Time since initial `Log::setLogger()` call in milliseconds
    "OffsetMs" => "0.0079ms"    // Time since the previous `Log::entry( .. precision: true )` call in milliseconds
]

记录器

提供的Logger类是一个符合PSR-3规范的记录器，扩展了Psr\Log\AbstractLogger，实现了Psr\Log\LoggerInterface接口。

它提供了对所有PSR-3方法的访问，并且是任何Psr\Log\LoggerInterface实例的即插即用替换。

此外，它还提供了一些管理日志条目的简单方法

$logger = new Northrook\Logger();

$logger->log( ... )          // log an entry using the PSR-3 standard
$logger->hasLogs() : bool    // check if there are any log entries
$logger->getLogs() : array   // get all log entries, without manipulating them
$logger->cleanLogs() : array // get all log entries, and clear them
$logger->clear()             // clear all log entries, without getting them
$logger->count() : int       // count all log entries
$logger->import( $logger )   // import log entries from another LoggerInterface
$logger->printLogs() : array // get an array of each entry as a human-readable string

printLogs() 方法用于快速打印所有日志条目。

默认情况下，它不会在日志前添加时间戳。将 true 作为第一个参数传递以添加时间戳。

// example:
$logger->entries = [ 
    0 => 'warning',
    1 => 'ile_get_contents(data.json): Failed to open stream: No such file or directory',
    2 => [ 'exception' => $exception ],
];

// default:
0 => 'Warning: file_get_contents(data.json): Failed to open stream: No such file or directory'

// with timestamp:
0 => '[2024-06-20T06:47:47+00:00] Warning: file_get_contents(data.json): Failed to open stream: No such file or directory'

如果在调用 cleanLogs() 之前销毁 Logger，则 printLogs() 方法将打印日志到 PHP 错误日志。

许可证

遵循 MIT 许可证，可在任何项目中免费使用。

致谢

BufferingLogger - Nicolas Grekas p@tchwork.com

northrook / logger

维护者

详情