README

什么是 Monolog Cascade？

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

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

安装

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

$ composer require theorchard/monolog-cascade

注意：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
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-2标准，有文档，并且包含单元测试。

接下来是什么？

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

Symfony用户

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

内部机制

如果您想了解更多关于实现的信息，请参阅Medium文章。

theorchard / monolog-cascade

维护者

详细信息