PHPackages                             maplephp/blunder - 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. [Debugging & Profiling](/categories/debugging)
4. /
5. maplephp/blunder

ActiveLibrary[Debugging & Profiling](/categories/debugging)

maplephp/blunder
================

Blunder is a well-designed PHP error handling framework.

v1.3.2(1mo ago)52352Apache-2.0PHPPHP >=8.2CI passing

Since Aug 12Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/MaplePHP/Blunder)[ Packagist](https://packagist.org/packages/maplephp/blunder)[ Docs](https://wazabii.se)[ RSS](/packages/maplephp-blunder/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (15)Used By (2)

MaplePHP Blunder
================

[](#maplephp-blunder)

[![Screen dump on how blunder looks like](https://camo.githubusercontent.com/011ec2e60c02587c63123934204e0ad4a063bdf47f87f64d7e305d83c3ae3568/68747470733a2f2f77617a616269692e73652f6769746875622d6173736574732f6d61706c657068702d626c756e6465722e706e67 "MaplePHP Blunder")](https://camo.githubusercontent.com/011ec2e60c02587c63123934204e0ad4a063bdf47f87f64d7e305d83c3ae3568/68747470733a2f2f77617a616269692e73652f6769746875622d6173736574732f6d61706c657068702d626c756e6465722e706e67)

**Blunder is a pretty error handling framework for PHP.** It provides a pretty, user-friendly interface that simplifies debugging with excellent memory management. Blunder offers various handlers, including HTML, JSON, XML, CLI, plain text, and silent modes, allowing flexible error presentation. Seamlessly integrating with tools like the PSR-7 and PSR-3 compliant MaplePHP Log library, Blunder is an excellent choice for managing errors in PHP applications, helping users easily identify and resolve issues.

With Blunder, you can easily control how errors are handled—whether you want to suppress specific severities, redirect them to logging, or assign them to different handlers. For example, you can automatically log all Deprecated warnings while keeping Warnings visible for debugging. This level of customization ensures a smooth and efficient error-handling experience tailored to your needs.

Installation
------------

[](#installation)

Installation with composer

```
composer require maplephp/blunder
```

Pretty Example
--------------

[](#pretty-example)

Here is a simple example to load the pretty error interface:

```
use MaplePHP\Blunder\Run;
use MaplePHP\Blunder\Handlers\HtmlHandler;

$run = new Run(new HtmlHandler());
$run->load();
```

Handlers
--------

[](#handlers)

All handlers utilize the namespace `MaplePHP\Blunder\Handlers\[TheHandlerName]`.

- **HtmlHandler**: A user-friendly and visually appealing handler.
- **TextHandler**: Outputs a minified HTML text.
- **PlainTextHandler**: Outputs minified plain text.
- **JsonHandler**: Outputs errors as JSON.
- **XmlHandler**: Outputs errors as XML.
- **CliHandler**: Prompt handler for the command-line interface (CLI)
- **SilentHandler**: Suppresses error output but can log errors to files. You can choose to output fatal errors if necessary.

Excluding Specific Error Severities from the Handler
----------------------------------------------------

[](#excluding-specific-error-severities-from-the-handler)

With Blunder, you can exclude specific error severities from the handler. This allows you to control how certain errors are processed without affecting the overall error handling behavior.

### 1. Exclude Severity Levels

[](#1-exclude-severity-levels)

This method removes the specified severities from Blunder’s handler, allowing them to be processed by PHP’s default error reporting.

```
$run = new Run(new HtmlHandler());
$run->severity()->excludeSeverityLevels([E_DEPRECATED, E_USER_DEPRECATED]);
$run->load();
```

**Effect:**

- `E_DEPRECATED` and `E_USER_DEPRECATED` will no longer be handled by Blunder.
- PHP’s default error handling will take over for these severities.

---

### 2. Exclude and Redirect Severities

[](#2-exclude-and-redirect-severities)

Instead of letting PHP handle the excluded severities, you can redirect them to a custom function for further processing, such as logging.

#### **Behavior:**

[](#behavior)

- **`return true;`** → Completely suppresses errors of the excluded severities.
- **`return false;`** → Uses PHP’s default error handler for the excluded severities.
- **`return null|void;`** → Keeps using Blunder’s error handler as usual.

```
$run = new Run(new HtmlHandler());
$run->severity()
    ->excludeSeverityLevels([E_DEPRECATED, E_USER_DEPRECATED])
    ->redirectTo(function ($errNo, $errStr, $errFile, $errLine) {
        error_log("Custom log: $errStr in $errFile on line $errLine");
        return true; // Suppresses output for excluded severities
    });
```

**Example Use Case:**

- Log warnings instead of displaying them.
- Ensure deprecated notices are logged but not shown in production.

---

### 3. Redirect Excluded Severities to a New Handler

[](#3-redirect-excluded-severities-to-a-new-handler)

You can also redirect excluded severities to a completely different error handler.

```
$run = new Run($errorHandler);
$run->severity()
    ->excludeSeverityLevels([E_WARNING, E_USER_WARNING])
    ->redirectTo(function ($errNo, $errStr, $errFile, $errLine) {
        return new JsonHandler();
    });
```

**Effect:**

- `E_WARNING` and `E_USER_WARNING` will be processed by `JsonHandler` instead of `HtmlHandler` or PHP’s default error handling.

---

**Note:**
You can find a full list of available PHP error severities [here](https://www.php.net/manual/en/errorfunc.constants.php).

---

Enabling or Disabling Trace Lines
---------------------------------

[](#enabling-or-disabling-trace-lines)

This allows you to control the level of detail shown in error messages based on your debugging needs. You can customize this behavior using the configuration:

```
$handler = new CliHandler();

// Enable or disable trace lines
$handler->enableTraceLines(true); // Set false to disable

$run = new Run($handler);
$run->load();
```

### **Options:**

[](#options)

- `true` → Enables trace lines (default in all cases except for in the CliHandler).
- `false` → Disables trace lines, making error messages cleaner.

This allows you to control the level of detail shown in error messages based on your debugging needs.

Remove location headers
-----------------------

[](#remove-location-headers)

This will remove location headers and make sure that no PHP redirect above this code will execute.

```
$run = new Run(new HtmlHandler());
$run->removeLocationHeader(true);
$run->load();
```

Setting the Exit Code for Errors
--------------------------------

[](#setting-the-exit-code-for-errors)

To make Blunder trigger a specific exit code when an error occurs. This is useful in unit testing and CI/CD, ensuring tests fail on errors.

```
$run = new Run(new CliHandler());
$run->setExitCode(1);
$run->load();
```

Event Handling
--------------

[](#event-handling)

You can use Blunder's **event** functionality to handle errors, such as logging them to a file. The example below shows how to display a pretty error page in development mode and log errors in production.

#### 1. Install MaplePHP Log

[](#1-install-maplephp-log)

We use [MaplePHP Log](https://github.com/MaplePHP/Log) in the example, a PSR-3 compliant logging library.

```
composer require maplephp/log
```

#### 2. Create an Event

[](#2-create-an-event)

Here is a complete example with explanatory comments.

```
// Add the namespaces
use MaplePHP\Blunder\Run;
use MaplePHP\Blunder\Handlers\HtmlHandler;
use MaplePHP\Blunder\Handlers\SilentHandler;
use MaplePHP\Log\Logger;
use MaplePHP\Log\Handlers\StreamHandler;

// Bool to switch between dev and prod mode
$production = true;

// Initialize Blunder
$handler = ($production ? new SilentHandler() : new HtmlHandler());
$run = new Run($handler);

// Create the event
$run->event(function($item, $http) use($production) {

    if ($production) {
        // Initialize the MaplePHP PSR-3 compliant log library
        $log = new Logger(new StreamHandler("/path/to/errorLogFile.log", StreamHandler::MAX_SIZE, StreamHandler::MAX_COUNT));

        // The code below uses "getStatus" to call PSR-3 log methods like $log->error() or $log->warning().
        call_user_func_array([$log, $item->getStatus()], [
            $item->getMessage(),
            [
                'flag' => $item->getSeverity(),
                'file' => $item->getFile(),
                'line' => $item->getLine()
            ]
        ]);
    }

});

// Load the error handling, and done
$run->load();
```

HTTP Messaging
--------------

[](#http-messaging)

The Blunder `Run` class can take two arguments. The first argument is required and should be a class handler (`HandlerInterface`). The second argument is optional and expects an HTTP message class used to pass an already open PSR-7 response and `ServerRequest` instance instead of creating a new one for better performance.

```
// $run = new Run(HandlerInterface, HttpMessagingInterface(ResponseInterface, ServerRequestInterface));
$run = new Run(new HtmlHandler(), new HttpMessaging($response, $request));
```

Exception Chaining
------------------

[](#exception-chaining)

When rethrowing an exception with a different type, PHP resets the file and line number to the location of the new `throw` statement. This can make debugging harder, as the error message will point to the wrong file instead of the original source of the exception.

To preserve the original exception’s file and line number while changing its type, you can use the **`preserveExceptionOrigin`** method provided by Blunder.

#### Example: Preserving the Original Exception’s Location

[](#example-preserving-the-original-exceptions-location)

```
try {
    // An exception has been triggered inside dispatch()
    $dispatch = $row->dispatch();
} catch (Throwable $e) {
    // By default, rethrowing with a new exception class changes the error location
    $exception = new RuntimeException($e->getMessage(), (int) $e->getCode());

    // Preserve the original exception's file and line number
    if (method_exists($e, "preserveExceptionOrigin")) {
        $e->preserveExceptionOrigin($exception);
    }

    throw $exception;
}
```

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance90

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 59.7% 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 ~49 days

Recently: every ~97 days

Total

13

Last Release

51d ago

PHP version history (2 changes)v1.0.0PHP >=8.0

v1.3.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/724b188e785081275926c5b9c07082e2b3f4afb797efdda61eb1630457e17824?d=identicon)[wazabii](/maintainers/wazabii)

---

Top Contributors

[![wazabii8](https://avatars.githubusercontent.com/u/6400238?v=4)](https://github.com/wazabii8 "wazabii8 (40 commits)")[![danielRConsid](https://avatars.githubusercontent.com/u/169045496?v=4)](https://github.com/danielRConsid "danielRConsid (27 commits)")

---

Tags

blunderdebugging-toolerrorerror-handlingerror-managementerror-presentationphpphp-errorspretty-error-interfacephperrorerror handlingdebugging-toolphp-errorspretty-error-interfaceerror-managementerror-presentationblunder

### Embed Badge

![Health badge](/badges/maplephp-blunder/health.svg)

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

###  Alternatives

[thehocinesaad/laravel-error-ai

This package adds Ask AI button to the error page.

2214.4k](/packages/thehocinesaad-laravel-error-ai)[h4cc/phpqatools

A meta composer package for PHP QA Tools.

6418.6k1](/packages/h4cc-phpqatools)

PHPackages © 2026

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