PHPackages                             eloquent/asplode - 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. eloquent/asplode

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

eloquent/asplode
================

Drop-in exception-based error handling for PHP.

2.2.0(10y ago)3865.6k↓35.7%3[2 issues](https://github.com/eloquent/asplode/issues)10MITPHPPHP >=5.3

Since Jul 2Pushed 10y ago2 watchersCompare

[ Source](https://github.com/eloquent/asplode)[ Packagist](https://packagist.org/packages/eloquent/asplode)[ Docs](https://github.com/eloquent/asplode)[ RSS](/packages/eloquent-asplode/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (10)Dependencies (5)Versions (16)Used By (10)

Asplode
=======

[](#asplode)

*Drop-in exception-based error handling for PHP.*

[![Current version image](https://camo.githubusercontent.com/3ff84016ff5a794e1c4996a186ff109e7760ba7f32469a593f57cdcb66630b8e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656c6f7175656e742f6173706c6f64652e7376673f7374796c653d666c61742d737175617265 "This project uses semantic versioning")](https://packagist.org/packages/eloquent/asplode)[![Current build status image](https://camo.githubusercontent.com/d4f8be7e3ff112efc943a5f7e6e89ac353f149c844d3600f6259e0e415abd5ff/687474703a2f2f696d672e736869656c64732e696f2f7472617669732f656c6f7175656e742f6173706c6f64652f646576656c6f702e7376673f7374796c653d666c61742d737175617265 "Current build status for the develop branch")](https://travis-ci.org/eloquent/asplode)[![Current coverage status image](https://camo.githubusercontent.com/74e0acc692ff8b893af866b032d11699c8250b67aad931855fdd668ecb43b9f2/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f656c6f7175656e742f6173706c6f64652f646576656c6f702e7376673f7374796c653d666c61742d737175617265 "Current test coverage for the develop branch")](https://codecov.io/github/eloquent/asplode)

Installation and documentation
------------------------------

[](#installation-and-documentation)

- Available as [Composer](http://getcomposer.org/) package [eloquent/asplode](https://packagist.org/packages/eloquent/asplode).
- [API documentation](http://lqnt.co/asplode/artifacts/documentation/api/) available.

Usage
-----

[](#usage)

The *Asplode* error handler can be installed with a single statement:

```
Eloquent\Asplode\Asplode::install();
```

What does *Asplode* do?
-----------------------

[](#what-does-asplode-do)

*Asplode* is a very simple PHP [error handler](http://php.net/set_error_handler) implementation that throws [ErrorException](http://php.net/ErrorException) exceptions instead of using the default PHP error handling behaviour. This means that all non-fatal runtime errors are presented to the developer in the form of an exception. It also means that any unhandled errors are delivered to a single point: the global exception handler.

Why use *Asplode*?
------------------

[](#why-use-asplode)

Developers need the ability to decide how their code behaves when an error occurs. Exceptions offer the only truly consistent way to report and recover from errors in PHP.

This method of handling errors has proven to be extremely effective. Similar strategies are used in major PHP frameworks such as [Laravel](http://laravel.com/). *Asplode* is a standalone implementation that can be used for any project.

Fatal error handling
--------------------

[](#fatal-error-handling)

While it's not feasible to *recover* from fatal PHP errors, it is possible to *report* fatal errors in the same manner as uncaught exceptions.

With *Asplode*, fatal errors cause a synthesized exception representing the fatal error to be passed to the global exception handler. This allows developers to gracefully inform the user of fatal errors just before the PHP interpreter is shut down.

The *Asplode* fatal error handler is installed by default, but is only activated if a global exception handler is installed.

```
set_exception_handler(
    function (Exception $e) {
        echo $e->getMessage();
    }
);

Eloquent\Asplode\Asplode::install();
```

To use *Asplode* without the fatal error handler, use `Asplode::installErrorHandler()` instead of `Asplode::install()`. To use only the fatal error handler, use `Asplode::installFatalHandler()`.

Note that attempting to autoload files in the shutdown phase of PHP may be probelmatic; and as such, custom exception handlers should explicitly load their dependencies where possible.

Asserting that the current error handler is compatible
------------------------------------------------------

[](#asserting-that-the-current-error-handler-is-compatible)

Code that assumes the use of *Asplode* may not work as expected unless the right type of error handler is installed. For example, code expecting to catch an `ErrorException` on failure will have unpredictable results if the installed error handler does not throw `ErrorException` instances.

To ensure that a correctly configured error handler is installed, *Asplode*provides the `Asplode::assertCompatibleHandler()` method.

```
use Eloquent\Asplode\Asplode;
use Eloquent\Asplode\Exception\ErrorHandlingConfigurationException;

try {
    Asplode::assertCompatibleHandler();
} catch (ErrorHandlingConfigurationException $e) {
    // handle appropriately
}
```

A *compatible* error handler is any handler that throws `ErrorException`exceptions. It does not need to be the implementation provided by *Asplode*.

Managing PHP's handler stacks
-----------------------------

[](#managing-phps-handler-stacks)

PHP's error and exception handlers approximate the behaviour of a [stack](http://en.wikipedia.org/wiki/Stack_(abstract_data_type)). However, the interface for manipulating the stack is limited, and quite frankly, poorly implemented.

*Asplode* includes two classes to aid in management of these stacks, [ErrorHandlerStack](http://lqnt.co/asplode/artifacts/documentation/api/Eloquent/Asplode/HandlerStack/ErrorHandlerStack.html) and [ExceptionHandlerStack](http://lqnt.co/asplode/artifacts/documentation/api/Eloquent/Asplode/HandlerStack/ExceptionHandlerStack.html). Both implement [HandlerStackInterface](http://lqnt.co/asplode/artifacts/documentation/api/Eloquent/Asplode/HandlerStack/HandlerStackInterface.html) which provides a familiar interface for working with stacks. These classes do not require the use of the *Asplode* handler; they can be used in a standalone manner to manage the handler stacks.

Migrating existing code to work with Asplode
--------------------------------------------

[](#migrating-existing-code-to-work-with-asplode)

When the *Asplode* error handler is installed, the [error\_reporting](http://php.net/error_reporting) setting will no longer have any effect. Notices, warnings, and errors will all result in an exception being thrown. Deprecation notices will not throw an exception, but will still be logged provided that PHP is configured to do so.

Code that has been written to handle legacy-style PHP errors will most likely need to be re-written. As an example, this type of logic:

```
$fp = fopen('/path/to/foo', 'r'); // this throws a PHP warning if the file is not found

if ($fp === false) {
  // handle error opening file
}
```

would need to be rewritten to to handle exceptions:

```
try {
  $fp = fopen('/path/to/foo', 'r');
} catch (ErrorException $e) {
  // handle error opening file
}
```

It's important to note that PHP can be very inconsistent in the way it reports error conditions. Some functions will return a boolean false to indicate an error has occurred; others may require the developer to call additional functions to check for errors; and others still may exhibit entirely non-standard behaviour.

*Asplode* does not free the developer from the responsibility of reading the PHP documentation, or making sure that they account for all possible error conditions.

Executing legacy code
---------------------

[](#executing-legacy-code)

Sometimes working with code that uses bad practices is unavoidable. A legacy PHP library might be perfectly functional and useful, but it may not anticipate exceptions being thrown when an error occurs.

*Asplode*'s exception and error handler stacks both implement an `executeWith()`method that allows code to be executed with a different handler than the one currently installed. This method pops all current handlers off the stack temporarily, installs the specified handler (if one is provided) and executes the supplied callback. The original handler is restored after the callback is executed.

```
use Eloquent\Asplode\HandlerStack\ErrorHandlerStack;

$stack = new ErrorHandlerStack;

$result = $stack->executeWith(
    function () {
        // this code will be executed under the default handler
    }
);

$result = $stack->executeWith(
    function () {
        // this code will be executed under the supplied handler
    },
    'errorHandlerFunctionName'
);

$result = $stack->executeWith(
    function () {
        // this code will be executed under the supplied handler
    },
    function ($severity, $message, $path, $lineNumber) {
        // handle the error
    }
);
```

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity40

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 94.3% 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 ~126 days

Recently: every ~248 days

Total

12

Last Release

3682d ago

Major Versions

1.1.1 → 2.0.02014-01-25

PHP version history (2 changes)1.0.0PHP >=5.3.0

2.0.0PHP >=5.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/100152?v=4)[Erin](/maintainers/ezzatron)[@ezzatron](https://github.com/ezzatron)

---

Top Contributors

[![ezzatron](https://avatars.githubusercontent.com/u/100152?v=4)](https://github.com/ezzatron "ezzatron (66 commits)")[![jmalloc](https://avatars.githubusercontent.com/u/761536?v=4)](https://github.com/jmalloc "jmalloc (4 commits)")

---

Tags

exceptionerrorhandlinghandlerfailureerrorexceptionfault

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/eloquent-asplode/health.svg)

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

###  Alternatives

[filp/whoops

php error handling for cool kids

13.2k402.4M1.4k](/packages/filp-whoops)[ikkez/f3-falsum

Pretty error handling for Fat-Free Framework

21145.8k3](/packages/ikkez-f3-falsum)[kuria/error

Makes handling and debugging PHP errors suck less

1920.0k2](/packages/kuria-error)[thehocinesaad/laravel-error-ai

This package adds Ask AI button to the error page.

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

PHPackages © 2026

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