README

什么是 Monolog Cascade？

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

它受到了 logging.config Python 模块的影响。

安装

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

$ composer require suvera/monolog-cascade:dev-master

注意：Monolog Cascade 需要 PHP 5.3.9 或更高版本。

使用方法

<?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

• 处理器 - 从 Yaml 或 JSON 衍生的关联数组（其中每个键是处理器标识符），它包含配置您的处理器的键/值。
  以下键是 预留的

  • class（必需）：您想要使用的处理器类名

• 日志记录器 - 从 Yaml 或 JSON 衍生的数组（其中每个键是日志记录器标识符），可能仅包含一个 handlers 键和一个/或一个 processors 键。您可以选择您的日志记录器想要使用的处理程序和/或处理器。

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

参数情况

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

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 将查找这些参数并识别它们为可选的，并带有它们的默认值。因此，您可以在配置文件中省略它们。

部分和参数的顺序

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

额外参数（除构造函数之外）

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

1. 实例方法
   您的格式化程序或处理程序有一个接受参数作为输入的已定义方法。在这种情况下，您可以在配置文件中这样写：

   formatters:
     spaced:
         class: Monolog\Formatter\LineFormatter
         format: "%datetime% %channel%.%level_name%  %message%\n"
         include_stacktraces: true

   在此示例中，LineFormatter 类有一个 includeStacktraces 方法，它接受一个布尔值。此方法将在实例化时被调用。
   

2. 公共成员
   您的格式化程序或处理程序有一个可以设置的公共成员。

   formatters:
       spaced:
           class: Monolog\Formatter\SomeFormatter
           some_public_member: "some value"

   在此示例中，公共成员将在实例化时设置为传递的值。
   

3. 自定义处理程序函数
   请参阅 FormatterLoader::initExtraOptionsHandlers 和 HandlerLoader::initExtraOptionsHandlers。这些方法包含可以调用实例方法（如果需要）的闭包。闭包接受实例和参数值作为输入。

   self::$extraOptionHandlers = array(
       'Monolog\Formatter\LineFormatter' => array(
           'includeStacktraces' => function ($instance, $include) {
               $instance->includeStacktraces($include);
           }
       )
   );

   如果需要，您可以在运行时添加处理程序。（例如，如果您编写了自己的日志记录器处理程序）

运行测试

只需运行 Phpunit

$ phpunit tests/

贡献

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

确保您的代码遵循 PSR-2 标准，已文档化并且有单元测试。

接下来是什么？

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

Symfony 用户

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

内部结构

如果您想了解更多关于实现的详细信息，可以阅读这篇 Medium 文章。