README

什么是 Monolog Cascade？

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

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

此存储库已被 concrete 核心团队分叉。

安装

在您的 composer.json 文件中将 monolog-cascade 添加为需求项，或者运行

$ 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，则 Cascade 将默认为 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 会在将参数传递给构造函数之前，将所有参数名称内部转换为 驼峰式。

可选键

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文章。

concrete5 / monolog-cascade

维护者

详细信息