README

作者：Kevin Boyd (https://whateverthing.com)

贡献者

许可证：MIT

什么是Kaboom？

Kaboom帮助您应对长期项目中编码的现实。

它提供了一个接口，用于向项目中添加临时代码，这些代码需要在日历上预定日期后开始或停止运行，或者基于环境条件的安全保护。

...那么，为什么是Kaboom？

在我的职业生涯中，我遇到了许多Kaboom可以帮助的场景，但主要的一个似乎总是健忘。组织通常不会花时间回顾和清理，除非有明确的要求。这通常留给个人去记住返回某个任意旧项目并使之焕然一新。

通过向您的项目中添加Kaboom支持的陷阱，您可以安排由代码本身产生的未来提醒 - 直接进入您的日志和报告系统！

您还可以自定义陷阱行为。也许您不是在设定日历日期后记录，而是检测环境条件并抛出异常。这是Kaboom的原始用例，灵感来源于社交媒体网站'Twitter'上的一个笑话，开发者Jeremy Kendall。

"这是一个有用的库：一个检测你是否处于开发环境，如果错误报告不是-1则爆炸的库 :-)"

https://twitter.com/JeremyKendall/status/420672420253822976

过了一段时间，又有了另一个想法

"这是一个有趣的想法：时间待办事项..."

https://twitter.com/Beryllium9/status/1314780273398013952

代码注释声明了一个紧急待办任务。随后，一个if语句使用当前Unix时间戳（编码时的时间）加上1天（以秒为单位）来检测是否应该抛出RuntimeException以强制执行待办事项。

然后我想，为什么不将这个功能集成到Kaboom中，并使用它来帮助代码库对抗冗余？

如何使用Kaboom

Kaboom的默认行为是在条件满足时抛出KaboomException。

这是因为默认构造函数中使用了ExceptionHandler类。

ExceptionHandler - 示例 1

这里，我们设置了一条消息，从2020年10月20日开始"爆炸"。

$kaboom = new Kaboom();
$kaboom->afterMessage(
    "2020-10-20",
    "Fix this code or you'll be sorry! KAB-200"
);

ExceptionHandler - 示例 2

或者，我们可以回到Kaboom的原始灵感，如果错误报告不足以满足我们的环境，则"爆炸"。

$env = 'dev';
$kaboom = new Kaboom();
$kaboom->condition(
    fn () => strtolower($env) === 'dev' && error_reporting() !== -1,
    fn () => "Error reporting is not set correctly!",
);

配置自定义Kaboom处理器

Kaboom支持各种处理器，用于控制触发条件时的行为。

日志处理器

LoggingHandler - 示例 3

要将Kaboom配置为记录日志而不是抛出异常，请执行此操作

use Beryllium\Kaboom\Kaboom;
use Beryllium\Kaboom\Handlers\LoggingHandler;
use Psr\Log\LogLevel;

$kaboom = new Kaboom(
    new LoggingHandler($logger, LogLevel::ERROR)
);

$kaboom->afterMessage(
    "2020-10-31",
    "Fix this code or you'll be sorry! KAB-200"
);

这可能会变得有点长，这时依赖注入容器就会有所帮助。

例如，您可以配置LoggingHandler作为HandlerInterface的默认实现，这样就可以自动连接所有东西，您只需要请求$container->get(Beryllium\Kaboom\Kaboom::class)。

注意：LoggingHandler的第二个参数，日志级别是可选的。默认日志级别是WARNING。

空处理器

NullHandler - 示例 4

您可能想要为不同的环境设置不同的配置，例如不希望在生产环境中崩溃。

在这种情况下，您可以使用空处理程序。

use Beryllium\Kaboom\Kaboom;
use Beryllium\Kaboom\Handlers\NullHandler;
use Beryllium\Kaboom\Handlers\ExceptionHandler;

$kaboom = new Kaboom(
    $env === 'prod' ? new NullHandler() : new ExceptionHandler()
);

$kaboom->afterMessage(
    "2020-10-31",
    "Fix this code or you'll be sorry! KAB-200"
);

分组

也许您想要有多个处理程序，比如您已经编写了一个自定义的Slack处理程序（如果是这样，请将其贡献回来！！谢谢！！）。这就是GroupHandler出现的地方。

GroupHandler - 示例 5

use Beryllium\Kaboom\Kaboom;
use Beryllium\Kaboom\Handlers\GroupHandler;
use Beryllium\Kaboom\Handlers\LoggingHandler;
use Your\Custom\Namespace\SlackHandler;

$kaboom = new Kaboom(
    new GroupHandler([
        new LoggingHandler(),
        new SlackHandler(),
    ])
);

$kaboom->afterMessage(
    "2020-10-31",
    "Fix this code or you'll be sorry! KAB-200"
);

现在，Kaboom将遍历您提供的处理程序，记录消息并将消息发送到Slack（按此顺序）。

... 但为什么？

您可能会查看实现并认为，这只是一个if条件。是的，您是对的 - 但这不仅仅是那样。

Kaboom建立了意图。当您用它来包装某物时，您是在做一个声明。您在说这个if条件是特殊的。

也许您在说这段代码是临时的，可以在某个时候删除。

也许您在说这是一个重要的安全保护，但您希望能够轻松控制生产与开发行为以最小化用户影响。

也许您只是想要对代码库中散布的特定类型的if条件有更深入的了解。

无论如何，这个库都是为了满足您的需求 - 不论您是想获得有帮助的日志条目，还是只是寻找震撼性的Kaboom。

欢迎贡献

如果您有使Kaboom更广泛有用的想法，请添加问题或PR。

您在项目中发现Kaboom有用吗？在Mastodon上告诉我！

@kboyd@phpc.social

谢谢！

beryllium / kaboom

维护者

详情