README

Neat log 组件提供了一种干净且易于表达的 API，用于构建符合 PSR-3 的日志记录器，以满足您的需求。

入门指南

要安装此包，只需在命令行中运行 composer

composer require neat/log

日志记录

创建一个日志记录器就像创建一个实例并在其上调用任何日志方法一样简单。

<?php

$log = new Neat\Log\File('logs/app.log');

// Use a predefined log level
$log->debug('Just saying hi');
$log->info('Business as usual');
$log->notice('Now you might want to read this');
$log->warning('Getting a little uncomfortable here');
$log->error('Something has gone wrong');
$log->critical('Seriously!');
$log->alert('Get the defibrillators!');
$log->emergency('System passed away');

// Or any custom level
$log->log('meltdown', 'Clear the region ASAP!');

系统日志

要将消息发送到系统日志，只需创建一个 Syslog 实例。

<?php

// The first parameter is an identifier that gets prepended to each message.
$log = new Neat\Log\Syslog('AppIdentifier');

// Any of the default log levels are used to determine the syslog message priority
$log->info('...'); // logs a syslog entry with LOG_INFO priority

上下文

要提供与日志消息相关的上下文，请将描述上下文的数据作为关联数组传递到您的消息之后的日志中。

<?php

// Create a destination log first
$log = new Neat\Log\File('app.log');

// Works with all predefined log level methods
$log->info('Record deleted', ['by' => 'John']);

// The custom log method supports context too
$log->log('query', 'SELECT * FROM posts', ['duration' => '0.0001s']);

过滤器

要管理日志详细程度并省略不需要的消息，可以在现有的日志记录器之上堆叠 Filter 日志记录器。

<?php

use Neat\Log\File;
use Neat\Log\Filter;
use Neat\Log\Record;

// Create a destination log first
$log = new File('filtered.log');

// Then attach the Filter to log warnings and more severe entries only
$log = new Filter($log, new Filter\Severity('warning'));

// If you want to log messages matching a pattern, there's filter for that too:
$log = new Filter($log, new Filter\Pattern('/mail/'));

// The opposite is quite easy too
$log = new Filter($log, new Filter\Exclude(new Filter\Pattern('/mail/')));

// Filters are just callables that return a boolean. Roll your own if you like:
$log = new Filter($log, function(Record $record): bool {
    return strtoupper($record->message()) != $record->message(); // prevents ALL CAPS logs
});

// The filter logger even accepts multiple filters at once
$log = new Filter($log, new Filter\Severity('warning'), new Filter\Pattern('/keyword/'));

时间戳

当将日志记录到文件时，您可能希望包括每行日志条目的时间或级别等关键信息。时间戳日志记录器正是为此而设计的。

<?php

use Neat\Log\File;
use Neat\Log\Record;
use Neat\Log\Stamp;

// Create a log file first
$log = new File('stamped.log');

// Then stack the Stamp logger on top with a stamp implementation
$log = new Stamp($log, new Stamp\Time());

// The Time stamp allows for setting a custom format and timezone
$log = new Stamp($log, new Stamp\Time('Y-m-d H:i:s.uO', 'europe/amsterdam'));

// Stamps are just callables returning a string that will precede each message:
$log = new Stamp($log, function (Record $record) {
    return strlen($record->message()) . ' bytes';
});

// Just like the Filter logger, you can use multiple stamps
$log = new Stamp($log, new Stamp\Time(), new Stamp\Level());

生成的日志文件将如下所示

[2018-09-23T14:34:20+0200] [debug] Just saying hi
[2018-09-23T14:53:08+0200] [error] Something has gone wrong

处理

为了增强、格式化或更改日志输出，您可以使用 Process 日志记录器。此日志记录器允许您完全修改和重写日志消息。

<?php

use Neat\Log\File;
use Neat\Log\Process;

// Like the other addon loggers, you'll need a log destination first
$log = new File('processed.log');

// Then you can add placeholder substition using the placeholder processor
$log = new Process($log, new Process\Placeholder());
$log->info('User {user} wrote a new post titled "{title}"', ['user' => 'John', 'my post title']);

// Or have your messages truncated above a specified message length
$log = new Process($log, new Process\Truncate(80));

// Or have all context appended to each log entry
$log = new Process($log, new Process\Context());

组合所有功能

当您组合这些日志记录器时，可以创建如下的真正整洁的日志组合。

<?php

use Neat\Log\File;
use Neat\Log\Filter;
use Neat\Log\Process;
use Neat\Log\Stamp;

$log = new File('logs/app.log');
$log = new Filter($log, new Filter\Severity('warning'));
$log = new Stamp($log, new Stamp\Time(), new Stamp\Level());
$log = new Process($log, new Process\Truncate(80));
$log->info('To log or not to log, that is the question');

您甚至可以使用 Manifold 日志记录器一次性写入多个日志记录器或日志记录器组合。

<?php

use Neat\Log\File;
use Neat\Log\Filter;
use Neat\Log\Stream;
use Neat\Log\Manifold;

$output = new Stream(STDOUT);
$file   = new Filter(new File('logs/app.log'), new Filter\Severity('error'));
$log    = new Manifold($output, $file);
$log->info('This message will only be printed on the standard output');
$log->error('This one will be written to both standard output and logfile');

弹性

Neat Log 组件乐于处理您向其抛出的任何类型的日志条目。这意味着您可以使用自定义日志级别、对象而不是字符串，甚至数组，而无需在日志和错误处理程序之间造成无限循环。它只是工作。