README

Monolog Cascade 是什么？

Monolog Cascade 是一个 Monolog 扩展，允许您从单个配置文件设置和配置多个日志记录器和处理器。这是一个分支，旨在快速且精简。

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

安装

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

$ composer require mattyg/monolog-cascade

注意：Monolog Cascade 的这个分支需要 PHP 5.6 或更高版本。

使用

<?php
use MattyG\MonologCascade\Cascade;

$config = json_decode(file_get_contents("/path/to/some/config.json"), true);
// Or if you prefer YAML
$config = yaml_parse_file("/path/to/some/config.yml");

// configure your loggers
Cascade::configure($config);

然后只需按照以下示例使用您的日志记录器

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

配置您的日志记录器

此分支的 Monolog Cascade 只支持作为数组传递的配置。这允许您以任何所需的格式存储配置，并避免了检查配置时使用的格式的运行时成本。

配置结构

以下是一个示例 JSON 配置文件

{
    "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"]
        }
    }
}

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

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

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

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

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

如果没有提供类，则 Cascade 将默认使用 Monolog\Handler\StreamHandler
处理器 - 一个数组，其中每个键是处理器标识符，包含配置您处理器的键/值。
以下键是保留的
- class（必需）：您想使用的处理器类名
日志记录器 - 一个数组，其中每个键是日志记录器标识符，可能只包含一个handlers键和一个/或一个processors键。您可以选择您的日志记录器想要使用的处理器和/或处理器。

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

可选键

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

默认参数

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

部分和参数的顺序

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

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

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

实例方法
您的格式化程序或处理器有一个定义的方法，该方法接受一个参数作为输入。在这种情况下，您可以在配置文件中这样写：
```
"formatters": {
    "spaced": {
        "class": "Monolog\\Formatter\\LineFormatter",
        "format": "%datetime% %channel%.%level_name%  %message%\n",
        "includeStacktraces": true
    }
}
```
在这个例子中，LineFormatter类有一个接受布尔值的includeStacktraces方法。此方法将在实例化时被调用。

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

"formatters": {
    "spaced": {
        "class": "Monolog\\Formatter\\SomeFormatter",
        "somePublicMember": "some value"
    }
}

在这个例子中，公共成员将在实例化时设置为传入的值。

自定义处理器函数
请参阅FormatterLoader::initExtraOptionsHandlers和HandlerLoader::initExtraOptionsHandlers。这些方法包含可以调用实例方法的闭包。闭包接受实例和参数值作为输入。
```
self::$extraOptionHandlers = array(
    '\Monolog\Formatter\LineFormatter' => array(
        'includeStacktraces' => function ($instance, $include) {
            $instance->includeStacktraces($include);
        }
    )
);
```
如果需要，您可以在运行时添加处理器。（例如，如果您为实例编写日志记录器处理器）

运行测试

只需运行Phpunit。

$ phpunit tests/

贡献

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

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

接下来是什么？

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

mattyg / monolog-cascade

维护者

详细信息