Log

Testing Is Documentation

tests/Log/LogTest.php

日志记录统一由日志组件完成，通常我们使用代理 \Leevel\Log\Proxy\Log 类进行静态调用。

内置支持的 log 驱动类型包括 file、syslog，未来可能增加其他驱动。

TIP

日志遵循 PSR-3 规范，用法与主流框架完全一致。

使用方式

使用容器 logs 服务

\App::make('logs')->emergency(string|\Stringable $message, array $context = []): void;
\App::make('logs')->alert(string|\Stringable $message, array $context = []): void;
\App::make('logs')->critical(string|\Stringable $message, array $context = []): void;
\App::make('logs')->error(string|\Stringable $message, array $context = []): void;
\App::make('logs')->warning(string|\Stringable $message, array $context = []): void;
\App::make('logs')->notice(string|\Stringable $message, array $context = []): void;
\App::make('logs')->info(string|\Stringable $message, array $context = []): void;
\App::make('logs')->debug(string|\Stringable $message, array $context = []): void;

依赖注入

class Demo
{
    private \Leevel\Log\Manager $log;

    public function __construct(\Leevel\Log\Manager $log)
    {
        $this->log = $log;
    }
}

使用静态代理

\Leevel\Log\Proxy\Log::emergency(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::alert(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::critical(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::error(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::warning(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::notice(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::info(string|\Stringable $message, array $context = []): void;
\Leevel\Log\Proxy\Log::debug(string|\Stringable $message, array $context = []): void;

log 配置

系统的 log 配置位于应用下面的 config/log.php 文件。

可以定义多个日志连接，并且支持切换，每一个连接支持驱动设置。

<?php

declare(strict_types=1);

return [
    /*
     * ---------------------------------------------------------------
     * 默认日志驱动
     * ---------------------------------------------------------------
     *
     * 系统为所有日志提供了统一的接口，在使用上拥有一致性
     */
    'default' => Leevel::env('LOG_DRIVER', 'file'),

    /*
     * ---------------------------------------------------------------
     * 允许记录的日志级别
     * ---------------------------------------------------------------
     *
     * 默认为 info
     */
    'level' => [
        \Leevel\Log\ILog::DEFAULT_MESSAGE_CATEGORY => Leevel::env('LOG_DEFAULT_LEVEL', \Psr\Log\LogLevel::INFO),
    ],

    /*
     * ---------------------------------------------------------------
     * 频道
     * ---------------------------------------------------------------
     *
     * 隔离不同环境的日志
     */
    'channel' => Leevel::env('ENVIRONMENT', 'development'),

    /*
     * ---------------------------------------------------------------
     * 日志连接参数
     * ---------------------------------------------------------------
     *
     * 这里为所有的日志的连接参数，每一种不同的驱动拥有不同的配置
     * 虽然有不同的驱动，但是在日志使用上却有着一致性
     */
    'connect' => [
        'file' => [
            // driver
            'driver' => 'file',

            // 驱动类
            'driver_class' => \Leevel\Log\File::class,

            // 频道
            'channel' => null,

            // 日志文件名时间格式化
            // 使用 date 函数格式化处理
            'name' => 'Y-m-d',

            // 默认的日志路径
            'path' => Leevel::storagePath('logs'),

            // 日志行时间格式化，支持微秒
            'format' => 'Y-m-d H:i:s u',

            // 日志文件权限
            'file_permission' => null,

            // 是否使用锁
            'use_locking' => false,
        ],

        'syslog' => [
            // driver
            'driver' => 'syslog',

            // 驱动类
            'driver_class' => \Leevel\Log\Syslog::class,

            // 频道
            'channel' => null,

            // 存储 \Monolog\Handler\AbstractSyslogHandler
            'facility' => LOG_USER,

            // 日志行事件格式化，支持微秒
            'format' => 'Y-m-d H:i:s u',
        ],
    ],
];

log 参数根据不同的连接会有所区别，通用的 log 参数如下：

配置项	配置描述
level	允许记录的日志级别
channel	频道

Uses

<?php

use Leevel\Filesystem\Helper;
use Leevel\Kernel\Utils\Api;
use Leevel\Log\File;
use Leevel\Log\ILog;
use Monolog\Logger;
use PHPUnit\Framework\Attributes\DataProvider;
use Psr\Log\InvalidArgumentException;
use Psr\Log\LogLevel;

log 基本使用

除了 PSR-3 支持的方法外，系统还提供了一些额外方法。

支持的日志类型

# Tests\Log\LogTest::baseUseProvider
public static function baseUseProvider(): array
{
    return [
        ['emergency'],
        ['alert'],
        ['critical'],
        ['error'],
        ['warning'],
        ['notice'],
        ['info'],
        ['debug'],
    ];
}

public function testBaseUse(string $level): void
{
    $log = $this->createFileConnect();

    $this->assertInstanceof(ILog::class, $log);

    self::assertNull($log->{$level}('foo', ['hello', 'world']));

    self::assertInstanceOf(Logger::class, $log->getMonolog());
    Helper::deleteDirectory(__DIR__.'/cacheLog');
}

日志支持等级过滤

public function testLogFilterLevel(): void
{
    $log = $this->createFileConnect([
        'level' => [
            ILog::DEFAULT_MESSAGE_CATEGORY => LogLevel::INFO,
        ],
    ]);
    $log->info('foo', ['hello', 'world']);
    $log->debug('foo', ['hello', 'world']);
    $fileInfo = __DIR__.'/cacheLog/development.info/*-'.date('Y-m-d').'.log';
    $fileDebug = __DIR__.'/cacheLog/development.debug/*-'.date('Y-m-d').'.log';
    self::assertTrue(is_file($fileInfo));
    self::assertTrue(!is_file($fileDebug));
}

日志支持消息分类

系统提供的等级 level 无法满足更精细化的日志需求，于是对消息 message 定义了一套规则来满足更精细的分类。

TIP

消息开头满足 [大小写字母|数字|下划线|中横线|点号|斜杆|冒号] 会被识别为消息分类。

public function testLogMessageCategory(): void
{
    $log = $this->createFileConnect();
    $log->info('[SQL] foo', ['hello', 'world']);
    $log->info('[SQL:FAILED] foo', ['hello', 'world']);
    $fileInfo1 = __DIR__.'/cacheLog/development.info/SQL:FAILED-'.date('Y-m-d').'.log';
    $fileInfo2 = __DIR__.'/cacheLog/development.info/SQL-'.date('Y-m-d').'.log';
    self::assertTrue(is_file($fileInfo1));
    self::assertTrue(is_file($fileInfo2));
}