PHPackages                             beryllium/kaboom - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. beryllium/kaboom

ActiveLibrary

beryllium/kaboom
================

It goes boom.

v2.0(2y ago)561MITPHPPHP >=8.0

Since Jan 10Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/beryllium/kaboom)[ Packagist](https://packagist.org/packages/beryllium/kaboom)[ RSS](/packages/beryllium-kaboom/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (4)Dependencies (2)Versions (5)Used By (0)

Kaboom
======

[](#kaboom)

Author: Kevin Boyd ()

Contributors:

- [Kevin Boyd](https://github.com/beryllium)
- [Jeremy Kendall](https://github.com/jeremykendall)

License: MIT

What Is Kaboom?
---------------

[](#what-is-kaboom)

Kaboom helps you deal with the realities of coding in long-term projects.

It provides an interface for controlling the age and stratification of your code.

With Kaboom, you can:

- Safely add temporary code to projects, without it becoming permanent
- Add code that needs to start or stop running after a specific calendar date
- Loudly call out code that should *NEVER* run in certain environments

### ... okay then, WHY Is Kaboom?

[](#-okay-then-why-is-kaboom)

In my career, I've encountered a number of scenarios that Kaboom can help with, but the main one always seems to be forgetfulness. Organizations often don't take the time to circle back and clean things up, unless it is specifically called out in some way. It's often left up to individuals to remember to return to some arbitrary old project and spruce it up.

By adding Kaboom-backed tripwires to your project, you can schedule future reminders that are emitted by the code itself - directly into your logging and reporting systems!

You can also customize the tripwire behaviour. Maybe instead of logging after a set calendar date, you would prefer to detect an environment condition and throw an exception. This was the original use case for Kaboom, inspired by a joke on an ancient social media website called 'Twitter' from developer Jeremy Kendall.

> "Here's a useful library: One that detects whether or not you're in a dev environment and explodes if error reporting isn't -1 :-)"

---

After a while, another idea arose:

> "Here's a fun idea: Temporal Todos ..."

> A code comment declares an urgent TODO task. Subsequently, an if statement uses the current unix timestamp (as of when it was coded) plus 1 day (in seconds) to detect if a RuntimeException should be thrown to enforce the TODO.

---

And then I thought, why not fold that functionality into Kaboom, and use it to help codebases fight back against cruft?

Getting Started
---------------

[](#getting-started)

To include Kaboom in your project, use composer:

```
composer require beryllium/kaboom

```

How to use Kaboom
-----------------

[](#how-to-use-kaboom)

### The Time Bomb

[](#the-time-bomb)

Kaboom's default behaviour is to throw a KaboomException if conditions are met.

**Example 1: `ExceptionHandler` with `->afterMessage()` condition**

Here, we set a message that will "go kaboom" starting on Oct 20, 2020.

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

**Example 2: `ExceptionHandler` with custom conditions**

Alternatively, we can harken back to the original Kaboom inspiration and "go kaboom" if error reporting is insufficient for our environment.

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

### Using a Custom Kaboom Handler

[](#using-a-custom-kaboom-handler)

Kaboom supports various Handlers that control how it behaves when a condition is tripped.

#### LoggingHandler

[](#logginghandler)

**Example 3: Injecting `LoggingHandler`**

To configure Kaboom to log instead of throwing an exception, build a `LoggingHandler` and pass it to `Kaboom`'s constructor:

```
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"
);
```

This can get a little lengthy, which is where a Dependency Injection Container would help.

For example, you could configure `LoggingHandler` to be the default implementation of `HandlerInterface`, which would then allow autowiring to wire things together so all you would have to request is `$container->get(Beryllium\Kaboom\Kaboom::class)`.

> **NOTE:** The second parameter of `LoggingHandler`, the Log Level, is optional. The default log level is `WARNING`.

#### Null Handler

[](#null-handler)

**Example 4: Exploding Quietly with `NullHandler`**

You may want to have different configurations for different environments, such as not wanting to blow up on Production.

In that case, you can use the Null handler:

```
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"
);
```

#### Grouped

[](#grouped)

Perhaps you want to have multiple handlers, such as if you've written a custom Slack handler (please contribute it back if so!! thanks!!). That's where the `GroupHandler` comes in.

**Example 5: Multi-Boom with `GroupHandler`**

```
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(), // NOTE: this handler does not yet exist!
    ])
);

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

Now, Kaboom will loop through your provided handlers and log the message and then send it to Slack (in that order).

... But Why?
------------

[](#-but-why)

You might look at the implementation and think, well, this is just an `if`condition. And yeah, you're right - but it's more than that.

Kaboom establishes intentionality.

When you use it to wrap something, you're making a statement. You're saying that this `if` condition is special, or maybe that the code is temporary and can be deleted at some point.

Maybe you're saying that it's an important safety protection, but you want to be able to easily control Production vs Development behaviour to minimize user impact.

Maybe you just want to have some deeper insight into a particular type of `if`condition that is peppered throughout your codebase.

Regardless, this library is here for your needs - whether you want a helpful log entry, or you're just looking for an earth-shattering Kaboom.

Contributions Welcome
---------------------

[](#contributions-welcome)

If you have ideas for making Kaboom more widely useful, please add Issues or PRs.

Have you found Kaboom to be useful in your projects? Let me know on Mastodon!

[@kboyd@phpc.social](https://phpc.social/@kboyd)

Thanks!

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance49

Moderate activity, may be stable

Popularity10

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1202 days

Total

4

Last Release

904d ago

Major Versions

v0.2 → v1.02020-10-10

v1.0 → v2.02023-11-25

PHP version history (2 changes)v0.2PHP >=7.4

v2.0PHP >=8.0

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/602491?v=4)[Kevin Boyd](/maintainers/beryllium)[@beryllium](https://github.com/beryllium)

---

Top Contributors

[![beryllium](https://avatars.githubusercontent.com/u/602491?v=4)](https://github.com/beryllium "beryllium (14 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/beryllium-kaboom/health.svg)

```
[![Health](https://phpackages.com/badges/beryllium-kaboom/health.svg)](https://phpackages.com/packages/beryllium-kaboom)
```

###  Alternatives

[elgg/elgg

Elgg is an award-winning social networking engine, delivering the building blocks that enable businesses, schools, universities and associations to create their own fully-featured social networks and applications.

1.7k15.7k5](/packages/elgg-elgg)[neos/flow

Flow Application Framework

862.0M451](/packages/neos-flow)[api-platform/metadata

API Resource-oriented metadata attributes and factories

223.5M96](/packages/api-platform-metadata)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[flowwow/cloudpayments-php-client

cloudpayments api client

2188.2k](/packages/flowwow-cloudpayments-php-client)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)