README

什么是 Monolog Cascade？

Monolog Cascade 是一个 Monolog 扩展，允许您从单个配置文件中设置和配置多个日志记录器和处理器。

它受到了 Python 模块 logging.config 的启发。

该存储库已被 concrete 核心团队分支。

安装

将 monolog-cascade 添加到您的 composer.json 文件中，或者运行

$ composer require concrete5/monolog-cascade

用法

<?php
use Cascade\Cascade;

// configure your loggers
Cascade::fileConfig('path/to/some/config.yaml');

// or use php array
$config = require 'config.php';
Cascade::fileConfig($config);

然后，只需像下面这样使用您的日志记录器即可

Cascade::getLogger('myLogger')->info('Well, that works!');
Cascade::getLogger('myLogger')->error('Maybe not...');

配置您的日志记录器

Monolog Cascade 支持以下配置格式

Yaml
JSON
返回数组的 PHP 文件
PHP 数组

配置结构

这是一个示例 Yaml 配置文件

formatters:
    dashed:
        class: Monolog\Formatter\LineFormatter
        format: "%datetime%-%channel%.%level_name% - %message%\n"
handlers:
    console:
        class: Monolog\Handler\StreamHandler
        level: DEBUG
        formatter: dashed
        processors: [memory_processor]
        stream: php://stdout
    info_file_handler:
        class: Monolog\Handler\StreamHandler
        level: INFO
        formatter: dashed
        stream: ./example_info.log
processors:
    web_processor:
        class: Monolog\Processor\WebProcessor
    memory_processor:
        class: Monolog\Processor\MemoryUsageProcessor
loggers:
    myLogger:
        handlers: [console, info_file_handler]
        processors: [web_processor]

这是一个示例 PHP 配置文件

<?php

return array(
    'version' => 1,

    'formatters' => array(
        'spaced' => array(
            'format' => "%datetime% %channel%.%level_name%  %message%\n",
            'include_stacktraces' => true
        ),
        'dashed' => array(
            'format' => "%datetime%-%channel%.%level_name% - %message%\n"
        ),
    ),
    'handlers' => array(
        'console' => array(
            'class' => 'Monolog\Handler\StreamHandler',
            'level' => 'DEBUG',
            'formatter' => 'spaced',
            'stream' => 'php://stdout'
        ),

        'info_file_handler' => array(
            'class' => 'Monolog\Handler\StreamHandler',
            'level' => 'INFO',
            'formatter' => 'dashed',
            'stream' => './demo_info.log'
        ),

        'error_file_handler' => array(
            'class' => 'Monolog\Handler\StreamHandler',
            'level' => 'ERROR',
            'stream' => './demo_error.log',
            'formatter' => 'spaced'
        )
    ),
    'processors' => array(
        'tag_processor' => array(
            'class' => 'Monolog\Processor\TagProcessor'
        )
    ),
    'loggers' => array(
        'my_logger' => array(
            'handlers' => array('console', 'info_file_handler')
        )
    )
);

有关 Cascade 配置解析器如何加载和读取参数的更多信息

仅需要 loggers 键。如果省略 formatters 和/或 handlers，则使用 Monolog 的默认设置。processors 是可选的，如果省略，则不使用任何处理器。（请参阅下面的“可选键”部分）。

其他键是可选的，其解释如下

formatters - 由 Yaml 或 JSON 生成的关联数组（其中每个键是格式化程序的标识符），它包含用于配置格式化程序的键/值。唯一的保留键是 class，它应包含您要使用的格式化程序的类名。其他参数将被解释为该类的构造函数参数，并在 Cascade 配置加载器实例化格式化程序对象时传递。
如果某些参数不在构造函数中，它们将被视为额外的参数，并且 Cascade 将尝试解释它们，如果它们与能够使用它们的任何自定义处理程序函数匹配的话。（请参阅下面的“额外参数”部分）

如果没有提供 class，则默认为 Monolog\Formatter\LineFormatter
handlers - 由 Yaml 或 JSON 生成的关联数组（其中每个键是处理程序的标识符），它包含用于配置处理程序的键/值。
以下键是保留的
- class（可选）：您要使用的处理程序的类名
- formatter（可选）：您已定义的格式化程序标识符
- processors（可选）：您已定义的处理程序标识符数组
- handlers（可选）：您已定义的处理程序标识符数组
- handler（可选）：您已定义的单个处理程序标识符
其他参数将被解释为该处理程序类的构造函数参数，并在 Cascade 配置加载器实例化处理程序对象时传递。
如果某些参数不在构造函数中，它们将被解释为额外的参数，并且 Cascade 将尝试解释它们，如果它们与能够使用它们的任何自定义处理程序函数匹配的话。（请参阅下面的“额外参数”部分）

如果没有提供类，Cascade 将默认使用 Monolog\Handler\StreamHandler
processors - 从 Yaml 或 JSON 生成的派生关联数组，其中每个键是处理器标识符，包含配置您的处理器的键/值。
以下键是 保留的
- class（必需）：您想要使用的处理器类名
loggers - 从 Yaml 或 JSON 生成的派生数组，其中每个键是记录器标识符，可能仅包含一个 handlers 键和一个/或一个 processors 键。您可以决定您想要使用的处理程序和/或处理器。

注意：如果您想要将对象作为处理程序的参数，可以使用带有相应参数的类名（使用 class 选项）来配置处理程序，就像配置处理程序一样。Cascade 递归实例化和加载这些对象，在解析配置文件时。请参阅此示例配置文件。

参数大小写

您可以在配置文件中使用 下划线 或 驼峰式 风格，这无关紧要。然而，它们必须与构造函数方法中的参数名称匹配。

public function __construct($level = Logger::ERROR, $bubble = true, $appName = null)

使用 Yaml 文件

    level: ERROR,
    bubble: true,
    app_name: "some app that I wrote"

Cascade 将在将参数传递给构造函数之前将所有参数名称 camelCase。

可选键

formatters、handlers 和 processors 键是可选的。如果省略，Cascade 将默认使用 Monolog 的默认格式化和处理程序：Monolog\Formatter\LineFormatter 和 Monolog\Handler\StreamHandler，输出到 stderr。如果省略 processors，则您的记录器将不会使用任何。

默认参数

如果构造函数方法在其声明中提供了默认值，Cascade 将查找并识别这些参数为可选参数及其默认值。因此，在您的配置文件中可以省略这些参数。

部分和参数的顺序

只要格式正确，配置文件中部分的顺序不会产生影响。
参数的顺序也不重要。

额外参数（除了构造函数的）

您可能希望您的格式化程序和/或处理程序消耗通过构造函数以外的值。一些方法可能在配置记录器时被调用以进行额外的设置。Cascade 以 3 种不同的方式解释这些额外参数，并按此顺序尝试这样做

实例方法
您的格式化程序或处理程序有一个定义的方法，该方法接受参数作为输入。在这种情况下，您可以在配置文件中这样写
```
formatters:
  spaced:
      class: Monolog\Formatter\LineFormatter
      format: "%datetime% %channel%.%level_name%  %message%\n"
      include_stacktraces: true
```
在此示例中，LineFormatter 类有一个 includeStacktraces 方法，该方法接受一个布尔值。该方法将在实例化时被调用。
公共成员
您的格式化程序或处理程序有一个可以设置的公共成员。
```
formatters:
    spaced:
        class: Monolog\Formatter\SomeFormatter
        some_public_member: "some value"
```
在此示例中，公共成员将在实例化时设置为传入的值。
自定义处理程序函数
请参阅 FormatterLoader::initExtraOptionsHandlers 和 HandlerLoader::initExtraOptionsHandlers。这些方法包含可以调用实例方法（如果需要）的闭包。闭包接受实例和参数值作为输入。
```
self::$extraOptionHandlers = array(
    'Monolog\Formatter\LineFormatter' => array(
        'includeStacktraces' => function ($instance, $include) {
            $instance->includeStacktraces($include);
        }
    )
);
```
如果需要，您可以在运行时添加处理程序。例如，如果您编写了自己的记录器处理程序）

运行测试

只需运行 Phpunit

$ phpunit tests/

贡献

此扩展是开源的。请随时贡献并发送拉取请求！

确保您的代码遵循 PSR-12 标准，已记录，并具有单元测试。

接下来是什么？

添加对 .ini 配置文件的支持
添加对命名空间化的Logger的支持，并实现消息传递（通过处理器继承），使子Logger使用父Logger的处理器来记录消息
添加更多自定义函数处理器，以覆盖当前Monolog格式化和处理器所有可能的选项
~~添加对处理器（已完成）的支持~~
~~添加对DB/Store和其他需要构造函数注入的处理器支持（问题 #30）（已完成）~~
还有其他建议吗？

Symfony 用户

您可能想使用 MonologBundle，因为它可以直接与您喜欢的框架集成。

内部机制

如果您想了解更多关于实现的信息，这里有一篇 Medium 文章。

concretecms / monolog-cascade

维护者

详细信息